Connect to a GitHub Enterprise host

Stay organized with collections Save and categorize content based on your preferences.

This page explains how to connect a GitHub Enterprise host to Cloud Build.

Before you begin

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

Required IAM permissions

To connect your GitHub Enterprise host, grant the Cloud Build Editor (roles/cloudbuild.builds.editor) role and the Cloud Build Integrations Owner (cloudbuild.integrations.owner) role to your user account.

To add the required roles to your user account, see Configuring access to Cloud Build resources. To learn more about IAM roles associated with Cloud Build, see IAM roles and permissions.

Connecting to a GitHub Enterprise host

You need to create a GitHub application on your GitHub Enterprise instance. The app sends webhook events to a Cloud Build endpoint. Upon receiving these events, Cloud Build will validate the payload and execute a build if the event corresponds to a Cloud Build GitHub trigger.

This sections explains how you can create a GitHub app:

  1. Log in to your GitHub Enterprise instance.
  2. Ensure you have latest version of GitHub Enterprise installed.

    Some versions of GitHub Enterprise may require SameSite cookies to be disabled in order to complete the following steps in a Chrome browser. If you are a version of GitHub Enterprise prior to the 2.21.3 release, you will need to disable SameSite cookies:

    1. Go to chrome://flags/.
    2. Type samesite in the filter bar.
    3. Make sure SameSite by default cookies is DISABLED.

      Screenshot of SameSite disabled

    4. Restart your browser.

  3. Open the Cloud Build Manage repositories page:

    Open the Manage Repositories page

  4. Click Connect host.

    You will see the Connect host panel, which prompts you to create a host connection to connect your GitHub Enterprise repositories to Cloud Build.

  5. In the Host URL section, enter the URL for your GitHub Enterprise instance. For example, ghe.example.com.

  6. In the API key section, click Generate to generate an API key or enter an API key if you already have one.

    If you want to manually create an API key, complete the following step:

    To obtain an API key:

    1. Open the Credentials page in the Cloud console:

      Open the Credentials page

    2. Click Create credentials.

    3. Click API Key.

      You will see a pop-up box with your API key created.

    4. Click Restrict key.

    5. Under API Restrictions, select Cloud Build API from the drop-down menu.

    6. Click Save.

  7. [OPTIONAL] In the Organization section, enter the organization the GitHub app will be created for. If this section is left blank, the app will be created under the current user account.

  8. [OPTIONAL] In the CA Certificate section, click Browse to upload your self-signed certificate. Your certificate must not exceed 10 KB in size and should be in PEM format (.pem, .cer, or .crt). If this section is left blank, a default set of certificates will be used in place.

  9. [OPTIONAL] In the Network section, enter the name of your Network project and a Network name for your network if your GitHub Enterprise instance is hosted in a private network. You need to complete this step if you want to build repositories in a private network. To learn more, see Build repositories from GitHub Enterprise in a private network .

  10. Click Connect Host.

    If your GitHub Enterprise instance is in a private network, the host connection process may take several minutes to complete.

  11. If you want to connect your repositories to Cloud Build, click Connect Repositories. Otherwise, click Done.

  12. After you connect your host, a pop-up box will appear prompting you to enter the name of your GitHub Enterprise app. Prior to entering the name of your app, you may be asked to log in. If you are using Google Chrome as your browser, the pop-up page may ask you to enter information about your GitHub Enterprise app manually.

  13. After logging in, enter a name for your GitHub app.

  14. Click Create GitHub App.

    You have just created a GitHub app on your GitHub Enterprise instance. Cloud Build will automatically store your credentials in Secret Manager and connect the host to your Cloud Project. In the API, this connection is represented as a GitHubEnterpriseConfig resource, or an association between Cloud Build and your GitHub Enterprise Server.

    Your host is now successfully connected. You can click on Connect Repositories if you want to connect repositories to Cloud Build. To learn more, see Connect to a GitHub Enterprise repository.

Next steps