Skip to main content

Integrating GitHub Enterprise with Bitrise

Abstract

Bitrise offers an integration to GitHub Enterprise Server (GHES). The main benefit of the integration is that GHES users can store the bitrise.yml file in their repository.

Bitrise offers an integration to GitHub Enterprise Server (GHES). The main benefit of the integration is that GHES users can store the bitrise.yml file in their repository. Storing the file in the repository allows for full version control and maintenance of your configuration file.

The feature requires:

  • A Bitrise Workspace owner to configure the integration.

  • A GHES organization owner with sufficient permissions to create a GitHub app on GHES and then install it for selected repositories.

  • Access to the GHES instance. If the Bitrise website cannot access your repository on GHES, it can't use the bitrise.yml file stored there. If you have IP address access control lists for security purposes, you need to allowlist the Bitrise website.

    Allowlisting the Bitrise website

    Be aware that the Bitrise website and the Bitrise build machines have a different IP address range. Allowlisting the build machines is not sufficient for this feature.

    If allowlisting is not an option for you, reach out to Bitrise so we can discuss other options.

To set up the integration, you need to:

Creating the GitHub app

  1. Log in to Bitrise and hover over the left navigation bar.

  2. Make sure you have the right Workspace selected.

  3. Select Settings.

    workspace-settings-new.png
  4. On the left of the Workspace settings page, select Integrations.

  5. Select the Git provider tab and scroll to the GitHub Enterprise Server section.

  6. Copy the webhook URL you can find here.

  7. In another browser tab, open GHES and go to your organization's Settings page.

    Target repository

    The organization should be the one that owns the repository or repositories that your app(s) use. You can reuse the GitHub app for other organizations later.

  8. On the Settings page, find the Developer settings section and select GitHub Apps.

  9. Click New GitHub App and fill out the app creation form. The following table contains all the necessary information and fields that aren't specified in the table can be left empty:

    Setting a webhook secret

    Setting a webhook secret is mandatory for this process and you will need the secret later when connecting your Bitrise Workspace to the GHES instance.

    Table 1. Required information for a new GitHub App

    GitHub App name

    Bitrise

    Homepage URL

    https://app.bitrise.io

    Webhook URL

    The one you copied from your Workspace settings page on Bitrise. The format should be: https://app.bitrise.io/organization/<org_slug>/github_webhooks

    Webhook secret

    GitHub marks this as optional but to ensure webhook integrity we require a secret to be set. The webhook secret should be a random string of text with high entropy. Please make a note of the secret as you have to share it with Bitrise later.

    Permissions

    Set the following permissions:

    • Repository permissions

      • Checks read and write

      • Commit statuses read and write

      • Contents read only

      • Metadata read only

      • Pull requests read only

    Upcoming features

    Bitrise will use these events and permissions to offer a fully integrated experience with supporting, for example, GitHub Checks and selective builds. We will add these capabilities soon.

    Subscribe to events

    Enable the following events:

    • Check run

    • Check suite

    • Pull request

    • Push

    Where can this GitHub App be installed?

    If you want to enable integration for repositories outside of this GHES organization, select Any account.


  10. When done, click Create GitHub App.

After creating the GitHub app, proceed to set up the GitHub Enterprise integration on Bitrise.

Connecting to the GHES instance via the GitHub app

After creating a new GitHub app, you need to connect your Bitrise Workspace to the GHES instance via the app:

Webhook secret required

Make sure you have the webhook secret from the GitHub app creation process available.

  1. Open your GitHub app's page: on your GitHub organization's Settings page, select GitHub apps and click Edit next to the app's name.

  2. On the left, select General.

  3. Generate a new client secret: find the «Client secrets and click Generate a new client secret. Copy the secret: you will need it later!

  4. Find the Private keys section and click Generate a private key. This downloads a .pem file which you will need to upload to Bitrise later in this process.

  5. On Bitrise, open the Workspace settings page and in the GitHub Enterprise Server section, click Connect.

  6. Fill out the connection form:

    • The Instance base URL can be found under Public link on the GitHub app's page.

    • Add the webhook secret and the client secret you generated earlier.

    • Upload the .pem file.

  7. When done, click Connect.

    Instant feedback

    You will receive immediate feedback about the connection and actionable error messages in the case of failure.

  8. Go back to GHES and open your GitHub app's page again.

  9. On the left, select Install app.

  10. Choose the organization(s) to install the app on.

  11. Under Repository access, select the repositories you want Bitrise to be able to access, or select all repositories.

  12. When done, click Save.

Bitrise receives a webhook event regarding the installation and automatically enables the corresponding Bitrise apps to use the recently set up GHES integration which you can check on the app settings page. Once this is done, you can now store your bitrise.yml file in a GHES repository: Storing the bitrise.yml file in your repository.

Testing the integration

We recommend testing the integration by creating a dummy app and store its bitrise.yml file on your GHES repository. You can use this demo app for testing purposes.

Troubleshooting the GHES integration

If the GHES integration doesn't work, you can:

  • Check the status of the integration on the Bitrise Integrations page.

  • Checking the webhook configuration and webhook deliveries on GitHub.

Checking the webhook configuration

  1. Open your GHES organization's page, and on the top navigation bar, select Settings.

  2. On the left, select Developer settings and then GitHub Apps.

  3. Find your GitHub app, and click Edit next to its name.

  4. On the left, select Advanced.

  5. Under the Recent deliveries section, check your webhook deliveries.

    If the webhook is configured correctly, you should see a 200 OK response with a green checkmark next to the deliveries.

  6. If your webhook deliveries failed:

    • Check the webhook URL on both Bitrise and on GitHub.

    • If necessary, re-create the webhook secret on GitHub and paste the new secret to the GHES integration on Bitrise.

Checking the integration on Bitrise

You can test the integration for any of the apps connected to your GHES instance.

Admin access only

Only users with the role of admin on the app's team can access all functions of the App Settings page of an app.

  1. Open your app on Bitrise.

  2. On the main page of the app, click on the App Settings icon: settings.svg.

    app-settings.png
  3. On the left of the Settings page, select Integrations.

  4. On the Git provider tab, find the Git integration status section.

  5. Next to the GitHub Enterprise Server Instance, click the Test connection button to test the connection.