AzureDevOpsScripts

The purpose of this AzureDevOpsScripts repository is to host and share any scripts I have created for working with Azure Dev Ops (ADO) and Git.

Update-ADOGit.ps1

The purpose of this script is to automate some of the the operations related to renaming a Git branch in an Azure DevOps Git project. The script can be used to update a branches in a single or all repositories in a project, as well as a single or all projects in an Azure Dev Ops organization.

This script will allow a user with appropriate permissions in an Azure DevOps (ADO) environment to complete the steps necessary to replace a default (top-level) branch with a newly created branch (e.g. replacing 'master' with 'main').
Specifically when all operations available in this script are executed, the following occurs:

1. Create a new branch in 1-to-all repositories in an ADO project, maintaining history of a specified existing "old" branch
2. Set that new branch as the default branch (i.e. top-level) branch for the repository
3. Copy all existing policies from an "old" branch to this new branch (project-level and repository-level policies) (see note)
4. Remove policies applying to "old" branch (project-level* and repository-level)
5. Delete the "old" branch
6. Update 1-to-all Build Pipeline definitions to use the new branch as the default branch for builds

NOTE: When all repositories are specified, project-level and repository-level policies are copied. When working on individual repositories, only the policies from those repositories are copied/removed.

Script Parameters

OrganizationName (String)

The name of the Azure DevOps organization hosting the project

ProjectName (String)

The name of the Azure DevOps project

OldBranchName (String)

The name of the existing or old branch that whose commit will be used as the base of the new branch. Specify this parameter when executing following Operations: All, AddBranch, CopyPolicies, DeletePolicies, DeleteBranch

NewBranchName (String)

The name of the new branch that will be created, using the commit number of the OldBranchName branch. Specify this parameter when executing following Operations: All, AddBranch, CopyPolicies, SetNewDefault

PersonalAccessToken (String)

The 64-bit string generated by the user in the user settings on the Azure DevOps website for the organization matching OrganizationName. A PersonalAccessToken must have at least the following granted for all operations in this script:

• Code: Read, Write, & Manage
• Build: Read & Execute
• Project and Team: Read, Write, & Manage

ReposToUpdate (String Array)

A single or list of repositories to update. Repositories are selected based on case-insensitive string match.

• For all repositories, use an asterisk. For example: -ReposToUpdate '*'
• For a single repository, specify the exact name (casing is ignored). For example: -ReposToUpdate 'tools1'
• For multiple repositories, specify a list of comma-separated items, using a PowerShell new array declaration. For example: -ReposToUpdate @('tools1', 'tools2', 'webdocs')
• Specify this parameter when executing following Operations: All, AddBranch, CopyPolicies, DeleteBranch, DeletePolicies, SetNewDefault

BuildDefsToUpdate (String Array)

A single or list of build definitions to update. Wildcards allowed (found via PowerShell -like).

• For all build pipeline definitions, use an asterisk. For example: -BuildDefsToUpdate '*'
• For a single build pipeline, use the exact name. For example: -BuildDefsToUpdate 'tools1 CI PR Build'
• For multiple build pipelines matching a single wildcard, use a simple string. For example: -BuildDefsToUpdate 'tools1*'
• For multiple build pipelines matching a multiple exact names or wildcard strings, use the PowerShell new array declaration. For example: -BuildDefsToUpdate @('tools1 CI PR Build', 'tools2*')
• Specify this parameter when executing following Operations: All, UpdateBuildDefs

Operations (String Array)

An optional parameter directing the actions of the script. If not included, 'All' operations is assumed. Script will validate against a set of known operations. Valid Operations:

• All: All of the operations specified.
• AddBranch: Add the NewBranchName to the repositories listed in the ReposToUpdate parameter
• DeleteBranch: Delete the OldBranchName from the repositories listed in the ReposToUpdate parameter
• SetNewDefaultBranch: Set the NewBranchName as the default branch in the repositories listed in the ReposToUpdate parameter
• CopyPolicies: Copy the policies applying to to OldBranchName and apply them to NewBranchName
  • If updating all repositories in a project (ReposToUpdate contains '*' ), this will include project-level policies and repository-level policies
  • If updating individual repositories in a project (ReposToUpdate does not contain '*'), this will include only the policies found in those repositories
• DeletePolicies: Delete the policies applying to OldBranchName
  • If updating all repositories in a project (ReposToUpdate contains '*' ), this will include project-level policies and repository-level policies
  • If updating individual repositories in a project (ReposToUpdate does not contain '*'), this will include only the policies found in those repositories
• UpdateBuildDefs: Update the Build Pipeline default branch for the build definitions specified in the BuildDefsToUpdate parameter

Examples

All Operations

In the 'MyProject' project of the 'Contoso' organization, replace the 'master' branch with 'main' in all repositories. Copy all project and repository policies that currently apply to master, to main. Update all build definitions to use 'main' as the new default branch for builds.

.\Update-ADOGit.ps1 -OrganizationName 'contoso' -ProjectName 'MyProject' -OldTopBranchName 'master' -NewTopBranchName 'main' -PersonalAccessToken 'PAT_64BIT_STRING' -ReposToUpdate '*' -BuildDefsToUpdate '*' -Operations 'All'

Copy/Move Policies for all Repositories in a Project

Move all policies from "dev" branch to "ppe" branch, for all repositories in the project. No branch is created or deleted in this example.

.\Update-ADOGit.ps1 -OrganizationName 'fabrikam' -ProjectName 'WebPlatform' -OldBranchName 'dev' -NewBranchName 'ppe' -PersonalAccessToken 'PAT' -ReposToUpdate '*' -Operations @('CopyPolicies', 'DeletePolicies')

Copy/Move Branch Policies for a Single Repository

Copy/Move Policies from "dev" branch to "ppe" branch, for only 'Tools1' repo. No branch is created or deleted in this example. To copy a policy without deleting the old one, omit the DeletePolicies operation.

.\Update-ADOGit.ps1 -OrganizationName 'contoso' -ProjectName 'WebPlatform' -OldBranchName 'dev' -NewBranchName 'ppe' -PersonalAccessToken 'PAT' -ReposToUpdate 'Tools1' -Operations @('CopyPolicies', 'DeletePolicies')

Delete a Branch and Branch Policies in all Repositories

Delete all policies for the "develop" branch, and then delete the branch.

.\Update-ADOGit.ps1 -OrganizationName 'contoso' -ProjectName 'WebData' -OldBranchName 'develop' -PersonalAccessToken 'PAT_64BIT_STRING' -ReposToUpdate '*' -Operations @('DeletePolicies', 'DeleteBranch')

Delete All Policies for a Branch in Multiple Repositories

Delete all policies for the "develop" branch in the tools1 and tools2 repositories, and then try to delete the branch.

.\Update-ADOGit.ps1 -OrganizationName 'fabrikam' -ProjectName 'WebData' -OldBranchName 'develop' -PersonalAccessToken 'PAT_64BIT_STRING' -ReposToUpdate @('tools1', 'tools2') -Operations @('DeletePolicies', 'DeleteBranch')

Create a New Branch in a Single Repository

Create a new branch called "stuff", with the history from existing branch called "things", in the repo "repo1".

.\Update-ADOGit.ps1 -OrganizationName 'myorg' -ProjectName 'proj1' -OldBranchName 'things' -NewBranchName 'stuff' -PersonalAccessToken 'PAT_64BIT_STRING' -ReposToUpdate 'repo1' -Operations 'AddBranch'

Configure a New Default Branch for a Single Repository

Configure a branch called "hockey" to be the default branch for the repository "winter"

.\Update-ADOGit.ps1 -OrganizationName 'sports' -ProjectName 'american' -NewBranchName 'hockey' -PersonalAccessToken 'PAT_64BIT_STRING' -ReposToUpdate 'winter' -Operations 'SetNewDefaultBranch'

Update Build Pipeline Defintions

Update all of the Build Pipeline definitions in the project "mudflaps" to use "bigtrucks" as the name of the default branch

.\Update-ADOGit.ps1 -OrganizationName 'vehiclethings' -ProjectName 'mudflaps' -NewBranchName 'bigtrucks' -PersonalAccessToken 'PAT_64BIT_STRING' -BuildDefsToUpdate '*' -Operations 'UpdateBuildDefs'