docs@
BuildMaster's primary integration point with Azure DevOps is source control stored in Azure Repos. This includes pulling source code, tagging it, and capturing commit IDs to maintain association between build artifacts and specific commits.
To get source code, use the AzureDevOps::Get-Source operation in a build or deployment plan. This operation supports various optional levels of granularity including the branch name to pull from, the tag name, or even specific Git references such as the commit ID.
An example of using the AzureDevOps::Get-Source operation is:
AzureDevOps::Get-Source
(
Organization: inedo,
Repository: ProfitCalc,
CommitHash => $CommitId
);
For illustrative purposes, this example is not using a DevOps Project Secure Resource as we recommend.
Azure DevOps supports two types of source control integration:
BuildMaster combined with the AzureDevOps extension only supports Git source control integration. To integrated with a TFVC source control system, you can use the BuildMaster TFS extension instead. Alternatively, you can convert existing TFVC repositories to Git repositories using the git-tfs tool available here: https://github.com/git-tfs/git-tfs
Git source repositories are unique in that you can use either a host-specific operation (in this case, AzureDevOps::Get-Source) or the generic Git::GetSource operation. The primary difference is that you'll use project names for Azure DevOps operations and URLs in the generic operations.
In general, you should prefer Azure DevOps-specific operations, because it's less data to enter and you may eventually move to a self-managed or private instance, which means you'll have to edit the URLs everywhere you entered them.
By default, BuildMaster does not require Git to be installed on a build server in order to perform source control operations. However, some users who require more advanced configuration for their Git integration may instruct BuildMaster to run the CLI instead by:
GitExePath operation property to a valid Git executable path, e.g. /usr/bin/git on Linux or C:\Program Files\Git\bin\git.exe on Windows$DefaultGitExePath variable at the server or system level in BuildMaster; this will force all Git source control operations to use the CLI instead of the built-in libraryGit repositories reference specific points in the history of a source tree using a 20-byte SHA1 hashcode. At the tip of a branch, this hash effectively represents the last committed changes. Capturing this reference at build time is very important so you can see exactly what code was used when an application was built:
BuildMaster gives you a lot of flexibility in capturing this information. Although you could always manually dig through the execution logs to find this information, a simpler approach is:
By simply specifying the CommitHash output parameter and the $CommitId runtime variable, the AzureDevOps::Get-Source operation will set the value of $CommitId to be the commit hash of the code. You can then use this to identify the entire source code state:
AzureDevOps::Get-Source
(
From: ProfitCalcRepo,
CommitHash => $CommitId,
);
Set-BuildVariable CommitId
(
Value: $CommitId
);
The second operation will then set $CommitId as a build variable, which means it will be not only visible on the build page, but you can use it in all future deployments on that build.
A 40-digit SHA1 code (i.e., a Git commit hash) is not at very user-friendly. Most web-based Git hosts will shorten these to eight characters for display purposes, while providing a hyperlink to view a page that shows the full commit.
You can do this in BuildMaster using a variable value renderer. These are essentially instructions for how to render variables in the UI that have certain names (such $CommitId). Because you can specify HTML in a value renderer, you link to your source control system while also providing a user-friendly code.
"Tagging" source code is essentially a way to give a user-friendly name to the state of your source code at a specific point in time. Like the little flags marking where a gas line lies underground, these tags help you find a specific code version among thousands or even millions of different versions.
Tags and labels can be used for all sorts of reasons, but they're most effective when used to identify which specific code was deployed to production. This makes it easy to:
If you're already capturing the commit ID in BuildMaster, each of these will already be possible. However, it's much easier for developers when this information in also source control: Not only is it faster to find information, but Git-based source control systems like Azure DevOps can use this commit ID in order to tag it later on in a build or release pipeline.
To tag source code in a repository, use the AzureDevOps::Tag, which will assign a friendly name (such as $ReleaseNumber.$BuildNumber) to a specific commit. This is recommended during later stages of a pipeline to indicate which specific commits have actually been released, as opposed to ones leading up to the eventual release.
This will tag a Azure DevOps-hosted repository with the current release and build number:
Azure DevOps::Tag
(
From: ProfitCalcRepo,
Tag: $ReleaseName-$BuildNumber,
CommitHash: $CommitId
);
By specifying $CommitId for the CommitHash parameter, this operation will likely not tag the current version of the code, but whatever version is represented by $CommitId. This could have been captured weeks prior.
Because a release-blocking defect can be discovered at any time prior to production, you can never be sure which specific build is deployed until after a build is deployed to production. Therefore, it's best to wait until after you've deployed to production to tag or label the code.
Is this documentation incorrect or incomplete? Help us by contributing!
This documentation is licensed under CC-BY-SA-4.0 and stored in GitHub.