Sending Build Status to Source Control

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

Similarly, the build status feature in Bitbucket Server displays the build status for the commit in the Bitbucket UI, and makes that information available through REST resources.

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:

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:

pipelines:
  - name: git_status_defaults
    steps:
      - name: status_update_defaults
        type: Bash
        configuration:
          inputResources:
            - name: myGitRepo
        execution:
          onStart:
            - update_commit_status myGitRepo                # Status: "processing"
          onExecute:
            - update_commit_status myGitRepo                # Status: "processing"
            - echo "Hello World!"
          onFailure:
            - update_commit_status myGitRepo                # Status: "failure"
          onSuccess:
            - update_commit_status myGitRepo                # Status: "success"

When the above example pipeline is run:

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.

The resources for the pipeline declares the GitRepo of the source control repository.

pipelines.resources.yml

resources:
  - name: myGitRepo
    type: GitRepo
    configuration:
      gitProvider: myGitHub
      path: myaccount/myproject

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.

pipelines.steps.yml

pipelines:
  - name: git_status_test
    steps:
      ##
      ## Step 1: Execute a simple, always successful test
      ##
      - name: success_test
        type: Bash
        configuration:
          inputResources:
            - name: myGitRepo
        execution:
          onStart:
            - update_commit_status myGitRepo --message "starting..." --context "$step_name"
          onExecute:
            - update_commit_status myGitRepo --message "running..." --context "$step_name"
            - echo "Hello World!"
          onFailure:
            - update_commit_status myGitRepo --message "Failed!" --context "$step_name"
          onSuccess:
            - update_commit_status myGitRepo --message "Succeeded :-)" --context "$step_name"
 
      ##
      ## Step 2: Execute a simple, always failing test
      ##
      - name: failure_test
        type: Bash
        configuration:
          inputResources:
            - name: myGitRepo
              trigger: false
          inputSteps:
            - name: success_test
        execution:
          onStart:
            - update_commit_status myGitRepo --message "starting..." --context "$step_name"
          onExecute:
            - update_commit_status myGitRepo --message "running..." --context "$step_name"
            - cd fail               # No such directory -- guaranteed to fail
          onFailure:
            - update_commit_status myGitRepo --message "Failed!" --context "$step_name"
          onSuccess:
            - update_commit_status myGitRepo --message "Succeeded :-)" --context "$step_name"

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:

update_commit_status myGitRepo --context "$pipeline_name:$run_number"