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 will 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 Buildkite Personal Settings.

To 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 and choose Repository Providers
  2. Click GitHub and select the GitHub Organization you want to connect to your Buildkite Organization
Screenshot of the Buildkite Repository Providers

You'll be prompted to give the GitHub App permission to submit commit statuses to your Organization's repositories. After that you can set up a pipeline.

To connect your Buildkite account to GitHub using OAuth

To connect your GitHub account open Buildkite’s Personal Settings, choose Connected Apps then click the GitHub Connect button:

Screenshot of the Buildkite Connected Apps screen

You'll be prompted to give permission for Buildkite to post status updates, and then redirected back to your Connected Apps page. After that you can set up a pipeline.

Setting up a new pipeline for a GitHub repository

  1. Create a new pipeline on Buildkite, using your GitHub repository URL in the form git@github.com:your/repo.

    Screenshot of adding a new pipeline
  2. Add at least one step to your pipeline, then click "Next". Change these steps at any time in Pipeline Settings.

  3. Follow the instructions on the page 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.

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

Branch configuration and Settings

You can edit the GitHub settings for each pipeline from the pipeline’s settings page:

Screenshot of the Buildkite GitHub settings

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.

  • Choose the 'build pull requests' checkbox.

Optionally, select one or more of the following:

  • limit pull request builds to certain branches.
  • skip pull request builds for commits that have already been built.
  • build pull requests that are ready for review.
  • build pull requests for forked repositories. Make sure to check the managing secrets guide if you choose to do this.
Screenshot of the Buildkite GitHub settings

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 (e.g. "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.

Screenshot of Branch Filter pattern

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.