en-US/about_AzDoGitRepository.help.txt
|
.NAME
AzDoGitRepository .SYNOPSIS This class represents an Azure DevOps Git repository. .DESCRIPTION The AzDoGitRepository class is a DSC resource that allows you to manage Azure DevOps Git repositories. It inherits from the AzDevOpsDscResourceBase class. Seeding a new repository from another Git source is create-time only: 'SourceRepository', 'SourceType' and 'ImportServiceConnectionName' are only ever read by New() and are listed in 'GetDscResourcePropertyNamesWithNoSetSupport()'. An existing repository is never re-imported by Set(), and diverging from whatever it was originally seeded with is not reported as drift by Test() - only 'IsDisabled' is compared/enforced on an existing repository. .PARAMETER ProjectName Required - System.String The name of the Azure DevOps project where the Git repository is located. .PARAMETER RepositoryName Key - System.String The name of the Git repository. This is the key property for the resource. .PARAMETER SourceRepository Write - System.String Optional. Seeds the repository at creation time. Its meaning depends on 'SourceType': a Git URL (for example 'https://github.com/MyUser/MyRepository.git') for an import, or 'Project/Repo' (or just 'Repo' for a repository in the same project) for a fork. When omitted, an empty repository is created. Ignored on an existing repository - never re-applied by Set(). .PARAMETER SourceType Write - System.String Allowed values: , Import, Fork Optional. Selects how 'SourceRepository' is used: 'Import' requests an import from an external Git URL, 'Fork' creates the repository as a fork of an existing Azure DevOps repository. When omitted and 'SourceRepository' is set, it defaults to 'Import' if the value looks like a URL (or an SSH remote, e.g. 'git@host:owner/repo.git'), and to 'Fork' otherwise. .PARAMETER ImportServiceConnectionName Write - System.String Optional. The name of a generic Git service connection (in the same project) that holds the credentials needed to import from a private 'SourceRepository' URL. Only used when 'SourceType' is 'Import'. Omit it for a public source. .PARAMETER IsDisabled Write - System.Boolean Optional. Disables or enables the repository. Unlike the source properties above, this is a plain repository property the API can update at any time, so it is compared and enforced on every Test()/Set() - not just at creation. Defaults to $false. .EXAMPLE 1 This example shows how to add the Git Repository, including seeding it from an existing source at creation time (issue #73). 'SourceRepository' is only ever used when the repository is created - it has no effect on an existing repository, and is never re-applied by Set(). 'SourceType' picks how 'SourceRepository' is used: - 'Import' clones the content of an external Git URL into the new repository via the Import Requests API. Inferred automatically when 'SourceRepository' looks like a URL (e.g. starts with 'https://' or is an SSH remote like 'git@host:owner/repo.git'). - 'Fork' copies an existing repository in this organization (either 'RepositoryName' in the same project, or 'ProjectName/RepositoryName' to fork from a different project). Inferred automatically otherwise. 'ImportServiceConnectionName' supplies the generic Git service connection used to authenticate an 'Import' against a private source repository. Omit it for a public source. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { # A plain, empty repository. AzDoGitRepository 'AddGitRepository' { Ensure = 'Present' ProjectName = 'Test Project' RepositoryName = 'Test Repository' } # Import the content of a public external Git repository. AzDoGitRepository 'ImportGitRepository' { Ensure = 'Present' ProjectName = 'Test Project' RepositoryName = 'Imported Repository' SourceRepository = 'https://github.com/octocat/Hello-World.git' } # Import the content of a private external Git repository, authenticating via a # generic Git service connection already configured in the project. AzDoGitRepository 'ImportPrivateGitRepository' { Ensure = 'Present' ProjectName = 'Test Project' RepositoryName = 'Imported Private Repository' SourceRepository = 'https://github.com/my-org/my-private-repo.git' ImportServiceConnectionName = 'GitHub-Import' } # Fork another repository already in this organization. AzDoGitRepository 'ForkGitRepository' { Ensure = 'Present' ProjectName = 'Test Project' RepositoryName = 'Forked Repository' SourceRepository = 'Other Project/Source Repository' SourceType = 'Fork' } } } .EXAMPLE 2 This example shows how to update the Git Repository. Set() only ever applies 'IsDisabled'. 'SourceRepository', 'SourceType' and 'ImportServiceConnectionName' seed a repository once, at creation time (see 1-AddAzDoGitRepository.ps1) - they are never re-applied and Test() never reports drift on them for a repository that already exists. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { AzDoGitRepository 'DisableGitRepository' { Ensure = 'Present' ProjectName = 'Test Project' RepositoryName = 'Test Repository' IsDisabled = $true } } } .EXAMPLE 3 This example shows how to remove a Git Repository. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { AzDoGitRepository 'RemoveGitRepository' { Ensure = 'Absent' ProjectName = 'Test Project' RepositoryName = 'Test Repository' } } } |