Automating creation of new ALM environments using PowerShell and Azure DevOps

Wouldn't it be great if you could stand up an entire ALM (Application Lifecycle Management) environment at the click of a button? With Azure DevOps, you can!

Azure DevOps (Azure DevOps) is a cloud collaboration tool for teams to share code, track work, and ship software. It has a number of key features to enable this including version control, work item tracking and dashboards, continuous integration and continuous delivery.

Wouldn't it be great if…

…you could then create a new project and all the related services such as version control and software builds with another click of a button? By using the Azure DevOps API, you can! (With a little upfront effort to bend the API to your will.)

The Azure DevOps API allows you to hook into your Azure DevOps instance to get, create, update and delete resources such as projects, repositories, build and releases. It is possible to interact with most of the services provided by Azure DevOps, offering great integrate with the platform.

In this post we'll take a look at how to get started with the Azure DevOps API, covering basic authentication and providing a number of PowerShell snippets demonstrating API usage. Using this post as a jumping off point, you could expand your usage of the API to fully automate creation of the complete ALM environment.

Authentication

You will need to use a "personal access token" to work with the API using basic authentication.

To do this, login to your Azure DevOps instance, and navigate to the "My Security" section by first clicking on your name in the top right of the navigation bar:

Then on the "Personal access tokens" page click "Add":

Create a personal access token using the inputs you like. It is possible to give an access token very specific access permissions by selecting a subset of authorized scopes, or leave it as the default "All scopes":

You'll only see the access token once right after you create it, so make sure to keep it somewhere save (for example in a password management service). The username that goes with this token is your own Azure DevOps username.

Working with the VSTS API from PowerShell

The Azure DevOps API has a full set of documentation, for example on how to get a list of builds. It gives the full URL and parameter set required for that particular API, plus examples of requests and responses (1).

The right-hand navigation (2) takes you through the current page (e.g. all the different build related operations), while the left-hand navigation (3) takes you through the different API resources (e.g. builds, releases, projects, repositories etc.)

When calling the API you need to pass a valid basic authentication header. To do this we'll use the personal access token created in the previous section.

The following PowerShell snippet shows how to build up the authentication header, by first base 64 encoding the username and access token then appending the result to the required "Basic "

You should end up with a value for the authentication header that looks like this: "Basic eW91ci5lbWFpbEBkb21haW4uY29tOmFiY2RlZmc="

Use this PowerShell snippet to call the API to get a list of build definitions for a particular project:

If you convert the result into JSON, it could later be used to create a new build definition, again via the API. You could even save the definition JSON to a file and commit to source control (along with all your other Infrastructure as Code artefacts for standing up a new environment).

Cloning a Project

Taking what we've just learnt, let's get a project definition using the API and then use that definition to create a new project.

The PowerShell script below first calls the Project API (line 22).

It then selects certain fields from the project definition result and removes others (line 24 and 25). This is because some fields are not needed by the API to create a new project (see the documentation to see what fields each API endpoint expects).

The project is then created (line 29). Notice that there are separate input parameters for source and destination. This means you could create the new project in the same Azure DevOps instance or an entirely different one depending on the requirement.

Cloning a Build

In a similar fashion to working with projects, we can also create a new build based on an existing one.

The following script (Get-VstsBuildDefinition.ps1) gets a build using the API and saves the resulting JSON build definition to a local path.

The next script (Create-VstsBuildDefinition.ps1) reads a build definition JSON file from a local path (line 17).

It then gets repository information for a given repository name (line 22). This is done because if you are creating the build in a different project, it will likely be linked to a different repository.

The repository information in the definition is updated, as is the name the build will be created with (lines 25-30).

There might be other parts of the build definition you wish to update at this point e.g. to add a new build step or change an existing one. If this was a release definition you might need to change the artefact links to be linked to the right build artefacts. This process will depend on your exact requirements and what the API allows.

The final build definition is then posted back to the Build API to create it (line 36). Again this could be in a completely different project or VSTS instance to the one you got the build definition from in the first place.

Next steps

In this post we have taken a look at how to get started with the Azure DevOps API, covering basic authentication and providing a number of PowerShell snippets demonstrating API usage.

Using this post as a jumping off point, you could expand your usage of the API to fully automate creation of the full ALM environment. Taken far enough, the API could be used to clone an entire Azure DevOps project including all of its resources like the repository, work items, builds and releases.