GitHub

Buildkite can connect to your GitHub repository and use the Commit Status API to update the status of commits in pull requests.

To complete this integration, you need admin privileges for your GitHub repository.

Connecting Buildkite and GitHub

You can now use our GitHub App to connect a Buildkite organization to a GitHub organization, removing the reliance on individual user connections to report build statuses. See the changelog announcement.

If you want to connect using OAuth you can still do so from your Personal Settings.

Connect your Buildkite account to GitHub using the GitHub App

Connecting Buildkite and GitHub using the GitHub App lets your GitHub organization admins see permissions and manage access on a per-repository basis.

  1. Open your Buildkite organization's Settings.
  2. Select Repository Providers > GitHub.
    Screenshot of the Buildkite Repository Providers
  3. Select Connect to a new GitHub Account. If you have never connected your Buildkite and GitHub accounts before, you will first need to select Connect and authorize Buildkite.
  4. Select the GitHub organization you want to connect to your Buildkite organization.
  5. Choose which repositories Buildkite should have access to, then select Install.

You can now set up a pipeline.

Connect your Buildkite account to GitHub using OAuth

To connect your GitHub account:

  1. Open Buildkite’s Personal Settings.
  2. Select Connected Apps.
  3. Select the GitHub Connect button:
    Screenshot of the Buildkite Connected Apps screen
  4. Select Authorize buildkite. GitHub redirects you back to your Connected Apps page.

You can now set up a pipeline.

Buildkite GitHub permissions

When you connect your GitHub organization, Buildkite needs the following permissions:

  • Read access to files located at .buildkite.yml: this allows Buildkite to access your file-based Buildkite configuration.
  • Read access to metadata: this is a default permission for all GitHub apps. From the GitHub documentation:

    GitHub Apps have the Read-only metadata permission by default. The metadata permission provides access to a collection of read-only endpoints with metadata for various resources. These endpoints do not leak sensitive private repository information.

  • Read and write access to checks, commit statuses, deployments, pull requests, and repository hooks: this is needed for Buildkite to perform tasks such as running a build on pull requests and reporting that build status directly on the PR on GitHub.

Set up a new pipeline for a GitHub repository

  1. Select Pipelines > New Pipeline New Pipeline
  2. Enter your pipeline details, including your GitHub repository URL in the form git@github.com:your/repo.

    Screenshot of adding a new pipeline
  3. If you are still using the web steps visual editor, add at least one step to your pipeline. Refer to Defining Steps - Adding steps for more information.

  4. Select Create Pipeline.

  5. Follow the onscreen instructions to set up a webhook:

    1. Add a new webhook in GitHub.
    2. Paste in the provided webhook URL.
    3. Select which events trigger the webhook.
  6. If using the YAML steps editor, add at least one step to your pipeline, then select Save and Build. Refer to Defining Steps - Adding steps for more information.

If you need to set up the webhook again, you can find the instructions linked at the bottom of the pipeline GitHub settings page.

You can edit your pipeline configuration at any time in Pipeline Settings.

Branch configuration and settings

You can edit the version control provider settings for each pipeline from the pipeline’s settings page. Go to Pipelines > Pipeline Menu > Pipeline Settings > <Provider>.

If you need more control over your pipeline configuration, add a pipeline.yml to your repository. Then you can use conditionals and branch filtering to configure your pipeline.

Running builds on pull requests

To run builds for GitHub pull requests, edit the GitHub settings for your Buildkite pipeline and choose the Build Pull Requests checkbox.

Optionally, select one or more of the following:

  • Limit pull request branches
  • Skip pull request builds for existing commits
  • Rebuild pull requests when they become ready for review
  • Build pull requests from third-party forked repositories. Make sure to check the managing secrets guide if you choose to do this.

If you want to run builds only on pull requests, set the Branch Filter Pattern in the pipeline to a branch name that will never occur (such as "this-branch-will-never-occur"). Pull request builds ignore the Branch Filter Pattern, and all pushes to other branches that don't match the pattern are ignored.

Noreply email handling

When you connect your GitHub account to Buildkite the email address associated with the GitHub account is added to your Buildkite account. If you've got GitHub set not to display your email, [username]@users.noreply.github.com or the more recent [username+id]@users.noreply.github.com is added instead. The email address of a commit is one of the ways Buildkite matches webhook builds to users.

Customizing commit statuses

The commit status is the label used to identify the Buildkite checks on your commits and pull requests on GitHub. Normally, Buildkite autogenerates these statuses.

For example, if you select Update commit statuses in your Pipeline Settings:

Screenshot of GitHub build settings with Update commit statuses enabled

Your checks will appear on your pull request as buildkite/<pipeline-name>:

Screenshot of the resulting GitHub pull request statuses

You can customize the commit statuses, for example to reuse the same pipeline for multiple components in a monorepo, at both the build and step level, using the notify attribute in your pipeline.yml.

Build level

  1. Add the following to your pipeline.yml, at the top level:

    notify:
        - github_commit_status:
            context: "my-custom-status"
    
  2. In Pipeline Settings > GitHub, make sure Update commit statuses is not selected. Note that this prevents Buildkite from automatically creating and sending statuses for this pipeline, meaning you will have to handle all commit statuses through the pipeline.yml.

  3. When you make a new commit or pull request, you should see my-custom-status as the commit status: Screenshot of GitHub build settings and the resulting GitHub pull request statuses

In a setup for a repository containing one codebase and one pipeline.yml, this customizes the commit status for the pipeline. However, if you have multiple pipeline.yml files in one repo, feeding in to the same Buildkite pipeline, this allows you to have different statuses when building different sections of the repo.

For example, if you have a monorepo containing three applications, you could use the same pipeline, with different pipeline.yml files for each application. Each pipeline.yml can contain a different GitHub status.

Step level

  1. Add notify to a command in your pipeline.yml:

    steps:
    - label: "Example Script"
        command: "script.sh"
        notify:
          - github_commit_status:
              context: "my-custom-status"
    
  2. In Pipeline Settings > GitHub, you can choose to either:

    • Make sure Update commit statuses is not selected. Note that this prevents Buildkite from automatically creating and sending statuses for this pipeline, meaning you will have to handle all commit statuses through the pipeline.yml.
    • Enable both Update commit statuses and Create a status for each job. Buildkite sends its default statuses as well as your custom status.
  3. When you make a new commit or pull request, you should see my-custom-status as the commit status: Screenshot of GitHub build settings and the resulting GitHub pull request statuses

Using one repository in multiple pipelines and organizations

If you want to use the same repository in multiple pipelines (including pipelines in different Buildkite organizations), you need to configure a separate webhook for each pipeline. Follow the webhook setup instructions in the Buildkite UI. Buildkite shows you these instructions when you create the pipeline, but you can also find them in Pipeline Settings > <Provider> > <Provider> Setup Instructions.

Build skipping

You may not always want to rebuild on every commit, or branch. You can configure Buildkite to ignore individual commits or branches, or to skip builds under certain conditions.