AzureDevOpsDscNative

1.1.0

en-US/about_AzDoSecureFile.help.txt

.NAME
    AzDoSecureFile
 
.SYNOPSIS
    DSC resource for managing Azure DevOps secure files.
 
.DESCRIPTION
    Manages the secure files a project makes available to its pipelines - certificates,
    keystores, provisioning profiles and similar secrets that do not belong in a variable group
    or in source control.
 
.PARAMETER ProjectName
    Required - System.String
    The name of the Azure DevOps project.
 
.PARAMETER SecureFileName
    Key - System.String
    The name of the secure file in Azure DevOps.
 
.PARAMETER FilePath
    Write - System.String
    The path of the local file to upload. Required when creating the secure file.
 
.PARAMETER Properties
    Write - HashTable
    Arbitrary key/value metadata stored alongside the file.
 
.PARAMETER ForceUpload
    Write - System.Boolean
    Re-upload the file on every run, replacing the stored content. Defaults to $false.
 
.EXAMPLE 1
 
This example uploads a certificate as a secure file so pipelines can consume it.
 
Configuration Example
{
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
 
    node localhost
    {
        AzDoSecureFile 'AddSigningCertificate'
        {
            Ensure = 'Present'
            ProjectName = 'MyProject'
            SecureFileName = 'signing.pfx'
            FilePath = 'C:\certs\signing.pfx'
        }
    }
}
 
.EXAMPLE 2
 
This example re-uploads a secure file on every run.
 
Azure DevOps never returns a secure file's content, so the resource cannot tell whether
the stored bytes still match the local file. ForceUpload is the way to say "the content
changes, replace it every time". It deletes and re-uploads, which changes the file's id.
 
Configuration Example
{
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
 
    node localhost
    {
        AzDoSecureFile 'RefreshSigningCertificate'
        {
            Ensure = 'Present'
            ProjectName = 'MyProject'
            SecureFileName = 'signing.pfx'
            FilePath = 'C:\certs\signing.pfx'
            ForceUpload = $true
            Properties = @{ environment = 'production' }
        }
    }
}
 
.EXAMPLE 3
 
This example removes a secure file.
 
The stored content cannot be recovered afterwards, and any pipeline referencing the file
will fail until it is replaced.
 
Configuration Example
{
    Import-DscResource -ModuleName 'AzureDevOpsDscNative'
 
    node localhost
    {
        AzDoSecureFile 'RemoveSigningCertificate'
        {
            Ensure = 'Absent'
            ProjectName = 'MyProject'
            SecureFileName = 'signing.pfx'
        }
    }
}