Source Control Build Status
An ability to log status information with your commits is a feature provided by many source control repository managers. Its availability and operation will differ according to your provider.
For example, the status checks feature of GitHub will mark each commit listed in the GitHub UI with the build status received, and the details of the status log can be viewed by clicking the mark. The build status log data can also be retrieved through the GitHub REST APIs
Sending Build Status from Pipelines
Where many CI automation servers require a plugin or custom integration to send build status to a source control repository, Pipelines provides a built-in utility function that can be used in any step.
To send build status from a pipeline step to a commit in a source repository, you must:
- Declare the GitRepo in the step's
- Use the
update_commit_statusutility function in any of the step's
The format of the
update_commit_status function is:
update_commit_status <gitRepo resource name> --status <status> --message <message> --context <context>
You must specify the GitRepo resource in the
update_commit_status function. The remaining parameters are all optional. By default, the function will infer the status from the
execution block where it is invoked. Default message and context strings are constructed from the step and pipeline name.
For example, this step will update the commit's build status for each execution phase using the defaults:
When the above example pipeline is run:
- The receiving source repository will create a status log entry for the step.
- Each call to
update_commit_statuswill overwrite the status and message values of that log entry.
The resulting build status log for the commit can be viewed in the source repository's UI (on GitHub):
The following example pipeline demonstrates sending build status messages to the source control repository that will create a status log entry for each executed step.
resources for the pipeline declares the GitRepo of the source control repository.
The pipeline consists of two dummy steps, one that will always execute successfully and one that will always fail to execute. The
update_commit_status function will send build status messages to the source repository for each step.
When viewed in the source repository's UI (on GitHub), the build status log for the commit shows both a successful and a failed execution of each step:
Note that since the context option is always set to the
$step_name environment variable in the example, the receiving source control repository will create a build status log entry for each step.
If you wanted to log only a single build status for the entire pipeline, you might set the context option to the
$pipeline_name environment variable instead. To log a build status for each run of the pipeline, you might combine it with the
$run_number environment variable:
update_commit_status myGitRepo --context "$pipeline_name:$run_number"