SCM status checks

caution

You must configure branch protections and checks, such as protection rules, CODEOWNERS, linting, and other checks or restrictions, in your source control provider.

If your pipelines use webhook triggers, you can get Harness build statuses in your PRs. However, you must configure your protection rules in your SCM provider if you want failed/running builds to block PR merges.

If you want to pull PR status check information into a Harness pipeline, you can add custom SCM status checks to your CI pipelines.

You can also use the Harness CI Jira plugin to update deployments and builds in Jira when your Harness pipelines run.

SCM links in build details

When viewing builds in Harness, builds triggered by webhooks can include a link to the PR or commit that started the build.

Pipeline links in PRs

When viewing a PR in your SCM provider, if a manual or webhook build ran from that PR, then you can follow the Details link from the PR's Git status to the build details page in Harness. This is supported for both manual and webhook PR builds, but it is not supported for all SCM providers.

Custom SCM status checks

If you want to pull PR status check information into a Harness pipeline, you can use Run steps to query your SCM provider's API and include custom SCM status checks in your CI pipelines.

Add a custom status check

These steps explain how to add a status check that uses the GitHub API. For information about leveraging another SCM provider's API, refer to that provider's API documentation.

1. You need a CI pipeline with a Build stage where you'll add the Run step. If you haven't created a pipeline before, try one of the CI pipeline tutorials.

2. Create GitHub Personal Access Token to use for authentication, and save the token as a Harness text secret.

3. Add a Run step to your Build (CI) stage.

4. Enter a Name for the step.

5. If required by your build infrastructure, provide the Container Registry and Image.

   • Container Registry is a container registry connector, such as a Docker connector.
   • Image is the FQN or artifact name and tag of a Docker image that has cURL installed, such as curlimages/curl:latest for the official cURL Docker Hub image.
   • To learn more about this setting and when it is required, go to Use Run steps - Container Registry and Image.

6. For Shell, select Sh.

7. In Command, enter a script that calls the GitHub API, for example:

   curl -i -X POST \
     -H "Authorization: Bearer <+secrets.getValue('account.YOUR_GITHUB_TOKEN_SECRET_ID')>" \
     -H "Accept: application/vnd.github.v3+json" \
     https://api.github.com/repos/YOUR_GITHUB_ORGANIZATION/<+pipeline.properties.ci.codebase.repoName>/statuses/<+codebase.commitSha> \
     -d '{"state":"pending","target_url":"<+pipeline.execution.url>","description":"Test is running","context":"harness-ci/tests"}'

   The above example calls the GitHub API and uses the GitHub token secret for authentication. It uses expressions to pull information from the pipeline, such as the target repository name (<+pipeline.properties.ci.codebase.repoName>) and the pipeline build link (<+pipeline.execution.url>).

   If you use the above script, replace YOUR_GITHUB_ORGANIZATION with your GitHub organization name, and replace YOUR_GITHUB_TOKEN_SECRET_ID with the ID of the Harness text secret that contains your GitHub personal access token.

8. Configure additional settings as necessary for your script and build infrastructure. For example, you might want to set container resource limits, export output variables, or inject environment variables. For more information about Run step settings, go to Use Run steps.

The above script is a basic GitHub status check. You can modify the script to include more commands, get other information from the payload, or call a different SCM provider's API. For example, the following script takes different actions depending on the resulting status, and it includes environment variables and conditional execution settings:

# status="<+execution.steps.STEP_ID.status>"
# name="harness-ci/tests"

echo "Send Commit Status"

if [[ "$status" == "SUCCEEDED" ]]; then
  state="success"
  description="$name scan passed for <+pipeline.properties.ci.codebase.repoName>"
elif [[ "$status" == "PENDING" ]]; then
  state="pending"
  description="$name scan pending for <+pipeline.properties.ci.codebase.repoName>"
else
  state="failure"
  description="$name scan failed for <+pipeline.properties.ci.codebase.repoName>"
fi

curl -i -u YOUR_GITHUB_ORGANIZATION:<+secrets.getValue("account.YOUR_GITHUB_TOKEN_SECRET_ID")> \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/YOUR_GITHUB_ORGANIZATION/<+pipeline.properties.ci.codebase.repoName>/statuses/<+codebase.commitSha> \
  -d "{\"state\":\"$state\",\"target_url\":\"<+pipeline.execution.url>\",\"description\":\"$description\",\"context\":\"$name\"}"

Create reusable status check steps

If you want to include status checks in multiple pipelines, you might want to create reusable templates or plugins.

Create a step template

Step templates help you quickly reuse customized or complex steps in multiple pipelines. For example, here is a YAML example of a step template for a GitHub status check step:

template:
  name: Send GitHub Status
  type: Step
  projectIdentifier: YOUR_HARNESS_PROJECT_ID
  orgIdentifier: YOUR_HARNESS_ORGANIZATION_ID
  spec:
    type: Run
    spec:
      connectorRef: account.harnessImage
      image: curlimages/curl:7.82.0
      shell: Sh
      command: |+
        # status="<+execution.steps.STEP_ID.status>"
        # name="harness-ci/tests"

        echo "Send Commit Status"

        if [[ "$status" == "SUCCEEDED" ]]; then
          state="success"
          description="$name scan passed for <+pipeline.properties.ci.codebase.repoName>"
        elif [[ "$status" == "PENDING" ]]; then
          state="pending"
          description="$name scan pending for <+pipeline.properties.ci.codebase.repoName>"
        else
          state="failure"
          description="$name scan failed for <+pipeline.properties.ci.codebase.repoName>"
        fi

        curl -i -u YOUR_GITHUB_ORGANIZATION:<+secrets.getValue("account.YOUR_GITHUB_TOKEN_SECRET_ID")> \
          -X POST \
          -H "Accept: application/vnd.github.v3+json" \
          https://api.github.com/repos/YOUR_GITHUB_ORGANIZATION/<+pipeline.properties.ci.codebase.repoName>/statuses/<+codebase.commitSha> \
          -d "{\"state\":\"$state\",\"target_url\":\"<+pipeline.execution.url>\",\"description\":\"$description\",\"context\":\"$name\"}"

      envVariables:
        status: <+input>
        name: <+input>
      imagePullPolicy: IfNotPresent
    when:
      stageStatus: Success
      condition: <+codebase.build.type>=="PR"
  identifier: Send_Git_Status
  versionLabel: 1.0.0

Write a custom plugin

You can package your status check script in a custom plugin and then add it to your pipelines in a Plugin step.

Troubleshoot status checks

Pipeline status updates aren't sent to PRs

Harness uses the pipeline's codebase connector to send status updates to PRs in your Git provider. If status updates aren't being sent, make sure that you have configured a default codebase and that it is using the correct code repo connector. Also make sure the build that ran was a PR build and not a branch or tag build.

Failed pipelines don't block PRs merges

Although Harness can send pipeline statuses to your PRs, you must configure branch protection rules and other checks in your SCM provider.