Building repositories from GitHub Enterprise

Cloud Build enables you to create triggers on a GitHub Enterprise instance. This page explains how you can use GitHub Enterprise triggers to invoke builds in response to commits or pull requests from a GitHub Enterprise instance.

Before you begin

  • Enable the Cloud Build and Secret Manager APIs.

    Enable the APIs

  • Ensure that you have the latest version of GitHub Enterprise.
  • Ensure you have admin access on repositories that you want to enable GitHub Enterprise triggers for.
  • Ensure you map a custom domain to your GitHub Enterprise host and have a valid SSL certificate for your host.

  • Create an API key that is restricted to the Cloud Build API.

  • If your GitHub Enterprise server is hosted in an on-premises environment, complete the following steps:

  1. Enable Private Google Access for on-premises hosts to make sure your GitHub Enterprise instance can reach Google Cloud APIs and Services.

  2. Peer your on-premises networks to Google Cloud and set up a Virtual Private Cloud (VPC) network. To learn more, see Peering a VPC network.

  3. Use private pools to run your builds. If you haven't, set up your project's environment and create a new private worker pool on your VPC. To learn how to run builds using a private worker pool, see Running builds in a private pool.

Required IAM permissions

To connect your GitHub Enterprise host, you require the Cloud Build Editor (roles/cloudbuild.builds.editor) role and the Cloud Build Integrations Owner (cloudbuild.integrations.owner) role added 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.

Peering a VPC network

If your GitHub Enterprise instance is hosted in an on-premises environment and not reachable over a public internet connection, you will need to peer your on-premises network to Google Cloud and set up a VPC network.

  1. Enable the Service Networking API.
  2. Create a new VPC Network or select an existing VPC network. Note: You must configure your VPC network to have access to your GitHub Enterprise instance on-premises.
  3. Allocate a named IP range in the VPC network. To use the VPC network with Cloud Build private pools, your prefix length must be /23 or lower, such as /22, /21, etc.
  4. Establish a VPC Network peering connection between your VPC network and Google Cloud. To learn more, see Creating a private connection.
  5. If you have DNS configured for your GitHub Enterprise instance, you will need to manually peer your DNS zone to our service provider. To learn more, see the Sharing private DNS zones with service producers.
  6. [OPTIONAL] If you do not want to peer the network from your Cloud project, you can set up a Shared VPC and have your Cloud project use that network instead if your project is part of an organization. You will still need the Shared VPC to be peered to the Service Networking API.

Creating a Cloud Build GitHub application

You will need to create a GitHub application on your GitHub Enterprise instance. The app will send 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. You will need to install the app on repositories you want to configure GitHub Enterprise triggers for.

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 on-prem and you have peered your network to Google Cloud.

  10. Click Connect Host.

    If your GitHub Enterprise instance is on a peered 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.

Connecting your GitHub Enterprise repositories

This section explains how you can map your Cloud project to the GitHub app you created in the previous section.

Console

  1. Open the Triggers page in the Google Cloud Console.

    Open the Triggers page

  2. Click Connect Repository.

  3. Under Select source, click on GitHub Enterprise.

  4. Select your Host Connection (GitHub Enterprise Config) from the drop-down menu.

  5. Click Continue.

  6. Authorize your application.

  7. Under Select repository, select your GitHub account and Repository from the drop-down menu.

API

To install the GitHub app on the appropriate GitHub user account or organization and connect it to a Cloud Build project:

  1. Naviagate to the URL associated with the GitHub app you created in the previous section:

       https://host-url/organizations/org-name/settings/apps/app-name/
    

    Where:

    • host-url is host url of your GitHub Enterprise instance.
    • org-name is the name of the organization where you created your project.
    • app-name is the name of your GitHub app.
  2. Install the app on your user account or organization via the URL.

    Once the app has been installed, take note of the installation ID associated with the app. The installation ID can be found in the URL after the app has been installed.

  3. Create a JSON file with the following contents:

    {
     "Id": installation-id,
     "project_id": "project-id",
     "repository_setting_list": {
            "repository_settings": {
            "owner": "owner",
            "name": "repo-name",
          },
          "repository_settings": {
            "owner": "owner",
            "name": "repo-name-additional"
          },
         …
     },
        "enterprise_config_resource_name": "projects/project-number/githubEnterpriseConfigs/id"
    }
    

    Where:

    • installation-id is the installation id of the GitHub app. Note: This value is an integer and does not require quotes.
    • project-id is the Cloud project associated with the installation.
    • owner is the owner of the GitHub repository.
    • repo-name is the name of the GitHub repository.
    • [OPTIONAL] repo-name-additional is the name of an additional GitHub repository.
    • project-number is the number of the Cloud project.
    • id is the ID of the GitHubEnterpriseConfig.
  4. Enter the following curl command in your terminal, where project-id is the Cloud project ID:

     curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/${PROJECT_ID}/installations -d @installation.json
    

The repositories associated with your installation are now viewable on the Triggers page under the Inactive tab.

Creating a GitHub trigger for your GitHub Enterprise installation

This section explains how you can create a trigger and link it your GitHub Enterprise installation. If you want to use GitHub Enterprise triggers in an on-premises environment, see Building repos in an on-premises environment from GitHub Enterprise for further instructions.

Console

To learn how to create triggers using the GitHub triggers, see Creating GitHub triggers.

API

The following JSON template shows you how you can create triggers via the command line:

  {
      "filename": "cloudbuild.yaml",
      "name": "curl-trigger",
      "description": "curl trigger",
      "github": {
          "push": {
              "branch": ".*",
          },
          "owner": "owner",
          "name": "repo-name",
      "enterprise_config_resource_name": "projects/project-number/githubEnterpriseConfigs/id"
      }
  }

Where:

  • owner is the owner of the GitHub repository.
  • repo-name is the name of the GitHub repository.
  • project-number is the number of the Cloud project.
  • id is the ID of your GitHubEnterpriseConfig.

Enter the following curl command in your terminal, where project-id is the Cloud project ID:

  curl -X POST -H "Authorization: Bearer "$(gcloud auth print-access-token) -H "Content-Type: application/json; charset=utf-8" https://cloudbuild.googleapis.com/v1/projects/project-id/triggers -d @trigger.json

Your trigger has now been created.

Building repos in an on-premises environment from GitHub Enterprise

This section explains how you can build in a private pool on a GitHub Enterprise instance using GitHub Enterprise triggers.

To create a GitHub Enterprise trigger to build in your on-premises environment:

  1. Enable Private Google Access for on-premises hosts to make sure your GitHub Enterprise instance can reach Google Cloud APIs and Services.

  2. Peer your on-premises network to Google Cloud and set up a Virtual Private Cloud (VPC) network. To learn more, see Peering a VPC network.

  3. Create a GitHub Enterprise trigger to build repositories hosted on a GitHub Enterprise instance.

Your GitHub Enterprise trigger will now automatically invoke builds on your GitHub Enterprise instance based on your configuration.

Next steps