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. The form requires:

  • The Client ID and Client Secret from the GitHub OAuth App you created in Step 1, and
  • The base URL of your GitHub Enterprise Installation

If you're using self-signed certificates, make sure the 'Verify TLS Certificate' checkbox is not checked.

Press Save GitHub Enterprise Settings to save your settings. After saving, the 'Secret' field will appear blank - it has been saved and will not be displayed on Buildkite.com.

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 allow Buildkite’s IP address so we can perform oAuth authentications use GitHub Enterprise API to update your pull request statuses.

All Buildkite network traffic to your GitHub Enterprise install will come from the following IP address: 54.165.103.71. Please configure your network to allow traffic from this IP address.

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;
    }

  }
}