Creating releases from a build server plugin on a version-controlled project

Octopus does not guess or auto-populate the commit or branch when creating a release from a build-server plug-in. Instead, to provide this information, we have added two new fields to our standard integrations - TeamCity, Azure DevOps, Jenkins, GitHub Actions, and Bamboo.

• Git Reference - a user-friendly alias for a commit hash. This is typically a branch name or tag.
• Git Commit - the commit SHA-1 hash.

The use of these fields can change depending on where the version-controlled project’s OCL files are stored:

1. If the OCL files are stored in the same repository as the application(s) being built, it’s likely that a specific commit that relates to any artifacts created as part of the build itself should be used when creating the release. In this scenario, you should provide both the Git Reference and Git Commit hash of the executing build. This ensures that the release will use the correct version of the project, and won’t include any potential changes made to the HEAD of the branch before the build has completed.
2. If the OCL files are stored in a different repository than the application(s) being built, a specific branch or tag can identify which version of the project to use when creating the release. In this case, you would provide the Git Reference where the OCL files are stored, and not the Git Commit hash. e.g. Use the main branch, regardless of the location of the repository where the application(s) are being built as they are different.

Below are some examples of how to auto populate these fields using build parameters for common build servers.

Azure DevOps

Azure DevOps stores information differently based on if the build is triggered by a branch push versus via a Pull Request (PR). You need to use a conditional statement to select the right variable. Here’s a suggested method to do so.

For Git Reference, use

$[coalesce(variables['system.pullRequest.sourceBranch'], variables['build.sourceBranch'])]

For Git Commit, use

$[coalesce(variables['system.pullRequest.sourceCommitId'], variables['build.sourceVersion'])]

Note: this approach doesn’t populate the commit details for manually triggered runs. It is recommended that you provide the values for both branch and commit in this case.

Github Actions

Github Actions provides different event data based on if the build is triggered by a branch push versus via a Pull Request (PR). You need to use a conditional statement to select the right variable. Here’s a suggested method to do so.

For Git Reference, use

${{ github.head_ref || github.ref }}

For Git Commit, use

${{ github.event.push.after || github.event.pull_request.head.sha }}

Note: this approach doesn’t populate the commit details for manually triggered runs. It is recommended that you provide the values for both branch and commit in this case.

TeamCity

TeamCity provides different data based on if the build is triggered by a branch push versus via a Pull Request (PR). There is no easy way to automate selecting the right one. Based on your process, we suggest using one of the following options.

Git reference

If the build is triggered by a branch push, use

%teamcity.build.branch%

If the build is triggered via a PR, use

%teamcity.pullRequest.source.branch%

Git commit

This is the same for both scenarios.

%build.vcs.number%

Notes

If multiple VCS sources are used in a build, remember to add the fully qualified parameter that includes the VCS Root ID. For example, teamcity.build.branch.<VCS_Root_ID> and build.vcs.number.<VCS_Root_ID>.

For a build resulting from a chained step, you may need to reference a parameter from the original build dependency. It will look something like this for a Git Commit - dep.<Dependant_Build_ID>.build.vcs.number or dep.<Dependant_Build_ID>.build.vcs.number.<VCS_Root_Id>.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Wednesday, October 4, 2023