en-US/about_AzDoBranchPolicy.help.txt
|
.NAME
AzDoBranchPolicy .SYNOPSIS DSC resource for managing Azure DevOps branch policies. .DESCRIPTION The AzDoBranchPolicy class manages branch policy configurations on a Git repository branch within an Azure DevOps project. A policy's full scope is a repository, a ref and how the ref is matched; RepositoryName and BranchName can each be left empty to widen that scope (see below), and PolicySettings drift is detected on whichever keys the configuration states, so raising an approver count or changing a build definition id is caught by Test() like any other property. .PARAMETER ProjectName Key - System.String The Azure DevOps project name. .PARAMETER RepositoryName Write - System.String The Git repository name. Leave empty for a cross-repository policy scope that applies to every repository in the project. .PARAMETER BranchName Write - System.String The branch ref name (with or without the 'refs/heads/' prefix), or a branch-name prefix when MatchKind is 'Prefix' (e.g. 'release/' matches every 'release/*' branch). Leave empty for a repository-wide policy scope with no branch restriction - only meaningful for policy types that do not require a ref, such as the repository settings policies (file size restriction, path length restriction, reserved names restriction, file name restriction, commit author email validation). .PARAMETER PolicyType Required - System.String The policy type display name (e.g. 'MinimumReviewerCount'). .PARAMETER PolicyIdentifier Write - System.String Optional. Azure DevOps allows several policies of the same PolicyType in the same scope (two build validation policies pointing at different pipelines, several status checks, a required-reviewers policy per path filter) but this resource has exactly one Key property (ProjectName), so a second discriminator is needed to give each one a stable identity. Set this to a value that appears among that policy's PolicySettings - a buildDefinitionId, a status check's name, a required reviewer's display name - and it is used, together with PolicyType and the scope, to tell the policies apart. Leaving it unset behaves exactly as before this property existed: the first policy of that type found in the scope is used, so a single-policy-per-type configuration needs no change. .PARAMETER MatchKind Write - System.String Allowed values: Exact, Prefix Optional. 'Exact' (default) matches BranchName as one branch. 'Prefix' matches every branch whose ref name starts with BranchName. .PARAMETER isEnabled Write - System.Boolean Whether the policy is enabled. Default is $true. .PARAMETER isBlocking Write - System.Boolean Whether the policy is blocking. Default is $true. .PARAMETER PolicySettings Write - HashTable Policy-type-specific settings hashtable. Only the keys present here are compared against the live policy's settings when checking for drift - a key the configuration does not state is left alone, never read as "must be empty". A 'scope' key, if supplied, overrides the scope this resource would otherwise build from RepositoryName/BranchName/MatchKind. .EXAMPLE 1 This example shows how to ensure that a minimum reviewer count branch policy exists on the 'main' branch of the 'MyRepository' repository. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { AzDoBranchPolicy 'AddBranchPolicy' { Ensure = 'Present' ProjectName = 'MyProject' RepositoryName = 'MyRepository' BranchName = 'refs/heads/main' PolicyType = 'MinimumReviewerCount' isEnabled = $true isBlocking = $true PolicySettings = @{ minimumApproverCount = 2 creatorVoteCounts = $false } } } } .EXAMPLE 2 This example shows how to update an existing branch policy, changing the minimum reviewer count and making it non-blocking. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { AzDoBranchPolicy 'UpdateBranchPolicy' { Ensure = 'Present' ProjectName = 'MyProject' RepositoryName = 'MyRepository' BranchName = 'refs/heads/main' PolicyType = 'MinimumReviewerCount' isEnabled = $true isBlocking = $false PolicySettings = @{ minimumApproverCount = 1 creatorVoteCounts = $true } } } } .EXAMPLE 3 This example shows how to scope a minimum reviewer count branch policy to every branch under a prefix (every 'release/*' branch) instead of one exact branch, and how to disambiguate a second policy of the same type in the same scope using PolicyIdentifier. Configuration Example { Import-DscResource -ModuleName 'AzureDevOpsDscNative' node localhost { # Applies to every branch whose name starts with 'release/', e.g. release/1.0, release/2.0 AzDoBranchPolicy 'ReleaseBranchesReviewerPolicy' { Ensure = 'Present' ProjectName = 'MyProject' RepositoryName = 'MyRepository' BranchName = 'release/' MatchKind = 'Prefix' PolicyType = 'MinimumReviewerCount' isEnabled = $true isBlocking = $true PolicySettings = @{ minimumApproverCount = 2 creatorVoteCounts = $false } } # A second MinimumReviewerCount policy on the same branch, distinguished from the # first by PolicyIdentifier so both can be managed independently. AzDoBranchPolicy 'MainBranchStrictReviewerPolicy' { Ensure = 'Present' ProjectName = 'MyProject' RepositoryName = 'MyRepository' BranchName = 'refs/heads/main' PolicyType = 'MinimumReviewerCount' PolicyIdentifier = '3' isEnabled = $true isBlocking = $true PolicySettings = @{ minimumApproverCount = 3 creatorVoteCounts = $false } } } } |