Skip to content

New-AdoCheckBranchControl.md

Latest commit

 

History

History
385 lines (317 loc) · 8.73 KB

New-AdoCheckBranchControl.md

File metadata and controls

385 lines (317 loc) · 8.73 KB

New-AdoCheckBranchControl

SYNOPSIS

Create a new branch control check for a specific resource.

SYNTAX

ByResourceName

New-AdoCheckBranchControl -ResourceType <string> -ResourceName <string>
 [[-CollectionUri] <string>] [[-ProjectName] <string>] [[-DisplayName] <string>]
 [[-AllowedBranches] <string[]>] [[-EnsureProtectionOfBranch] <bool>]
 [[-AllowUnknownStatusBranches] <bool>] [[-Timeout] <int>] [[-Version] <string>]
 [-WhatIf] [-Confirm] [<CommonParameters>]

ByResourceId

New-AdoCheckBranchControl -ResourceType <string> -ResourceId <string>
 [[-CollectionUri] <string>] [[-ProjectName] <string>] [[-DisplayName] <string>]
 [[-AllowedBranches] <string[]>] [[-EnsureProtectionOfBranch] <bool>]
 [[-AllowUnknownStatusBranches] <bool>] [[-Timeout] <int>] [[-Version] <string>]
 [-WhatIf] [-Confirm] [<CommonParameters>]

ALIASES

This cmdlet has the following aliases,

  • N/A

DESCRIPTION

This function creates a new branch control check for a specified resource within an Azure DevOps project. When existing configuration is found, it will be returned instead of creating a new one.

EXAMPLES

EXAMPLE 1

PowerShell

$params = @{
    CollectionUri              = 'https://dev.azure.com/my-org'
    ProjectName                = 'my-project-1'
    DisplayName                = 'Branch Control'
    ResourceType               = 'environment'
    ResourceName               = 'my-environment-tst'
    AllowedBranches            = 'refs/heads/main', 'refs/heads/release/*'
    EnsureProtectionOfBranch   = $true
    AllowUnknownStatusBranches = $false
    Timeout                    = 1440
}
New-AdoCheckBranchControl @params

Creates a new branch control check for the specified environment name with default parameters.

EXAMPLE 2

PowerShell

$params = @{
    CollectionUri              = 'https://dev.azure.com/my-org'
    ProjectName                = 'my-project-1'
    DisplayName                = 'Branch Control'
    ResourceType               = 'environment'
    ResourceId                 = '00000000-0000-0000-0000-000000000100'
    AllowedBranches            = 'refs/heads/main', 'refs/heads/release/*'
    EnsureProtectionOfBranch   = $true
    AllowUnknownStatusBranches = $false
    Timeout                    = 1440
}
New-AdoCheckBranchControl @params

Creates a new branch control check for the specified environment ID using the provided parameters.

PARAMETERS

-CollectionUri

Optional. The collection URI of the Azure DevOps collection/organization, e.g., https://dev.azure.com/my-org.

Type: System.String
DefaultValue: $env:DefaultAdoCollectionUri
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ProjectName

Optional. The name or id of the project.

Type: System.String
DefaultValue: $env:DefaultAdoProject
SupportsWildcards: false
Aliases:
- ProjectId
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-DisplayName

Optional. The name of the branch control check. Default is 'Branch Control'.

Type: System.String
DefaultValue: Branch Control
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ResourceId

Mandatory. The ID of the resource to which the check will be applied. If not provided, the function will attempt to resolve the ID based on the ResourceType and ResourceName.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: ByResourceId
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ResourceName

Mandatory. The name of the resource to which the check will be applied.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: ByResourceName
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-ResourceType

Mandatory. The type of resource to which the check will be applied. Valid values are 'endpoint', 'environment', 'variablegroup', 'repository'.

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: true
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues:
- endpoint
- environment
- variablegroup
- repository
HelpMessage: ''

-AllowedBranches

Optional. A comma-separated list of allowed branches. Default is 'refs/heads/main'.

Type: System.String[]
DefaultValue: refs/heads/main
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-EnsureProtectionOfBranch

Optional. Specifies whether to ensure the protection of the specified branches. Default is $true.

Type: System.Boolean
DefaultValue: True
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-AllowUnknownStatusBranches

Optional. Specifies whether to allow branches with unknown status. Default is $false.

Type: System.Boolean
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Timeout

Optional. The timeout in minutes for the approval check. Default is 1440 (1 day).

Type: System.Int32
DefaultValue: 1440
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Version

Optional. The API version to use for the request. Default is '7.2-preview.1'. The -preview flag must be supplied in the api-version for such requests.

Type: System.String
DefaultValue: 7.2-preview.1
SupportsWildcards: false
Aliases:
- ApiVersion
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues:
- 7.1-preview.1
- 7.2-preview.1
HelpMessage: The -preview flag must be supplied in the api-version for such requests.

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

  • N/A

OUTPUTS

PSCustomObject

NOTES

  • When a branch control check with the same configuration already exists, the existing check is returned with a warning
  • Only 'environment' resource type is currently supported
  • The check uses the 'evaluatebranchProtection' task definition
  • Requires authentication to Azure DevOps. Use Set-AdoDefault to configure default organization and project values.
  • The cmdlet automatically retrieves authentication through Invoke-AdoRestMethod which calls New-AdoAuthHeader.

RELATED LINKS