GitHub Enterprise

Buildkite can connect to your GitHub Enterprise installation and use the Commit Status API to update the status of commits in Pull Requests.

Step 1. Register Buildkite as an OAuth App

This guide was written using GitHub Enterprise version 2.16.3. Earlier or later versions may have different menus and headings for the OAuth app registration. All of the Buildkite settings will remain the same.

In your GitHub Enterprise organization settings, click on the 'OAuth Apps' menu item under 'Developer Settings':

Screenshot of the OAuth Apps Page in the Developer Settings Menu

Click Register an application. Fill out the form with the following values:

  • Name: Buildkite
  • URL: https://buildkite.com
  • Callback URL: https://buildkite.com/user/authorize/github_enterprise/callback
Screenshot of the form to Register an OAuth Application

Click the Register application button at the bottom of the form.

After sucessfully registering your application, you can optionally add a logo to your app. Here is a pre-cropped image you can use:

Buildkite Logo

Make a note of your Client ID and Client Secret, you will need those to connect your GitHub Enterprise installation with Buildkite in the next step.

Screenshot of the Client ID and Client Secret section of the Buildkite OAuth App settings page

Step 2. Update your Buildkite organization settings

Go to the Organization Settings page of the Buildkite organization you'd like to connect to your GitHub Enterprise installation:

Screenshot of the Buildkite menu bar with the organization settings link selected

Scroll down to the GitHub Enterprise settings section. Enter the Client ID and Client Secret from the GitHub OAuth App you created in Step 1. Enter the base URL of your GitHub Enterprise Installation to this form, then press Save GitHub Enterprise Settings.

Screenshot of the GitHub Enterprise settings section in Buildkite

Step 3. Connect your GitHub Enterprise account to Buildkite

For Buildkite to mark commits and pull requests as pass or fail, you'll need to authorize your GitHub Enterprise user account with Buildkite.

In your Buildkite Personal Settings, click on the Connected Apps menu item. Here you'll see your GitHub Enterprise Installation along with any other connected apps. Click Connect:

Screenshot of the Connected Apps page in Buildkite Personal Settings with the GitHub Enterprise App

You will be redirected back to your GitHub Enterprise Installation, where it will ask you to authorize your new Buildkite OAuth app to use your GitHub Enterprise account. Click Authorize to complete your setup:

Screenshot of the Authorization page in GitHub Enterprise

That's it! Next time you create a pipeline with a repository that's either https://git.mycompany.com/acme-inc/app.git or git@git.mycompany.com:acme-inc/app.git, Buildkite will recognize that it's hosted on your GitHub Enterprise Installation, and use your newly created OAuth authorization to update the commit statuses.

Firewalled installs

If your GitHub Enterprise is behind a firewall you’ll need to whitelist Buildkite’s network so we can perform oAuth authentications and call to the API to update your pull request statuses.

Whitelist the IP address 54.165.103.71 to allow Buildkite to perform API calls on your GitHub Enterprise instance.

For additional security you can create a proxy which allows only the API endpoints we require:

  • /api/v3/repos/.*/.*/statuses
  • /api/v3/user
  • /login/oauth

The following is an example NGINX server configuration that proxies the required URLs and can be used with the "Public API URL" GitHub Enterprise setting in Buildkite:

daemon off;

events {
  worker_connections 1024;
}

http {

  server {
    listen 443 ssl;

    location / {
      allow 54.165.103.71;
      deny all;
    }

    location ~ ^/api/v3/repos/.*/.*/statuses {
      proxy_pass https://ghe.internal:443;
    }

    location /api/v3/user {
      proxy_pass https://ghe.internal:443;
    }

    location /login/oauth {
      proxy_pass https://ghe.internal:443;
    }

  }
}