Connect to a GitHub Enterprise host

Console

To connect your GitHub Enterprise host to Cloud Build:

1. Open the Repositories page in the Google Cloud console.

   Open the Repositories page

   You will see the Repositories page.

2. In the project selector in the top bar, select your Google Cloud project.

3. At the top of the page, select the 2nd gen tab.

4. Click Create host connection to connect a new host to Cloud Build.

5. On the left panel, select GitHub Enterprise as your source provider.

6. In the Configure Connection section, enter the following information:

   1. Region: Select a region for your connection.

   2. Name: Enter a name for your connection.

7. In the Host details section, enter the following information:

   1. Host URL: Enter the host URL for your connection. For example, github.example.com

   2. CA Certificate: Click Browse to upload your self-signed certificate.

   3. Under Connection type, select one of the following options:

      1. Public internet: Select this option if your instance is accessible via the public internet.

      2. Private network access: Select this option if your instance is hosted in a private network.

      3. Under Service Directory service, selection the location for your service:

         • In project your-project
         • In another project
         • Enter manually

         1. If you select In another project or Enter manually, enter the following information:

            • Project: Enter or select your Google Cloud project ID from the drop-down menu.

            • Region: This field pre-selects the region of your connection. The region specified for your service must match the region associated with your connection.

         2. Namespace: Select the namespace of your service.

         3. Service: Select the service name in your namespace.

8. Click Connect.

   After clicking the Connect button, you will be asked to create a GitHub App in your GitHub Enterprise host and install the app in a user account or organization. An authentication token from your GitHub Enterprise host will be created and stored in this project as a Secret Manager secret. You may revoke access by uninstalling or deleting the GitHub app from your host at any time.

   Cloud Build stores the authentication data of the created GitHub App as secrets in Secret Manager in your project. This data includes your private key and webhook secret. The private key is used as an authentication method to access the API of the Enterprise Server. The webhook secret is used to validate the events sent from the server to Cloud Build. The Cloud Build Service Agent account (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com) is used to access your secret. To view your secret, see List secrets and view secret details.

   After authorizing the Cloud Build GitHub App, you will be redirected to the Cloud Build Repositories page.

You have now successfully created a GitHub Enterprise connection.

gcloud

To connect your GitHub Enterprise host to Cloud Build using gcloud commands, complete the following steps:

1. Enter the following command to create a GitHub Enterprise connection:

   gcloud builds connections create github-enterprise CONNECTION_NAME \
     --host-uri=HOST_URI --region=REGION
   

   Where:

   • CONNECTION_NAME is the name of your connection.
   • HOST_URI is the URI of your GitHub Enterprise instance. For example, https://mmy-ghe-server.net.
   • REGION is the region for your connection.

   If your GitHub Enterprise instance is in a private network, specify your Service Directory resource. You can also specify your CA certificate.

   --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
   --ssl-ca-file=SSL_CA_FILEPATH
   

   Where:

   • PROJECT_ID is your Google Cloud project ID.
   • REGION is the region for your connection.
   • NAMESPACE is the namespace for your service.
   • SERVICE_NAME is the name of your service in your namespace.
   • SSL_CA_FILEPATH is the file path to your CA certificate.

   After running the gcloud builds connections... command, you will receive a link to install the Cloud Build GitHub app.

2. Follow the link returned in the previous step to create and install the Cloud Build GitHub App on your enterprise server.

3. Enter the following command to verify your connection:

   gcloud builds connections describe CONNECTION_NAME --region=REGION
   

   Where:

   • CONNECTION_NAME is the name of your connection.
   • REGION is the region for your connection.

   If the installationState field is set to COMPLETE, you have successfully installed the connection. Otherwise, the installationState field provides a link for additional steps required.

You have now successfully created a GitHub Enterprise connection.

Terraform

Once you have installed your GitHub app, you can connect your GitHub Enterprise host to Cloud Build using the Google Terraform provider.

In the following example, the code snippet does the following:

• Configures the Terraform Google provider
• Creates a secret to store the GitHub App's private key and webhook secret
• Grants necessary permissions to the Cloud Build Service Agent to access secrets

• Creates a GitHub Enterprise connection

  // Configure the terraform google provider
  terraform {
    required_providers {
      google = {}
    }
  }
  
  // create Secrets and grant permissions to the Service Agent
  resource "google_secret_manager_secret" "private-key-secret" {
      project = "PROJECT_ID"
      secret_id = "PRIVATE_KEY_SECRET"
  
      replication {
          auto {}
      }
  }
  
  resource "google_secret_manager_secret_version" "private-key-secret-version" {
      secret = google_secret_manager_secret.private-key-secret.id
      secret_data = file("private-key.pem")
  }
  
  resource "google_secret_manager_secret" "webhook-secret-secret" {
      project = "PROJECT_ID"
      secret_id = "WEBHOOK_SECRET"
  
      replication {
          auto {}
      }
  }
  
  resource "google_secret_manager_secret_version" "webhook-secret-secret-version" {
      secret = google_secret_manager_secret.webhook-secret-secret.id
      secret_data = "WEBHOOK_SECRET_VALUE"
  }
  
  data "google_iam_policy" "serviceagent-secretAccessor" {
      binding {
          role = "roles/secretmanager.secretAccessor"
          members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"]
      }
  }
  
  resource "google_secret_manager_secret_iam_policy" "policy-pk" {
    project = google_secret_manager_secret.private-key-secret.project
    secret_id = google_secret_manager_secret.private-key-secret.secret_id
    policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
  }
  
  resource "google_secret_manager_secret_iam_policy" "policy-whs" {
    project = google_secret_manager_secret.webhook-secret-secret.project
    secret_id = google_secret_manager_secret.webhook-secret-secret.secret_id
    policy_data = data.google_iam_policy.serviceagent-secretAccessor.policy_data
  }
  
  // create the connection and add the repository resource ---
  resource "google_cloudbuildv2_connection" "my-connection" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "CONNECTION_NAME"
  
      github_enterprise_config {
          host_uri = "URI"
          private_key_secret_version = google_secret_manager_secret_version.private-key-secret-version.id
          webhook_secret_secret_version = google_secret_manager_secret_version.webhook-secret-secret-version.id
          app_id = "APP_ID"
          app_slug = "APP_SLUG"
          app_installation_id = INSTALLATION_ID
      }
  
      depends_on = [
          google_secret_manager_secret_iam_policy.policy-pk,
          google_secret_manager_secret_iam_policy.policy-whs
      ]
  }
  

Where:

• PROJECT_ID is your Google Cloud project ID.
• PRIVATE_KEY_SECRET is the secret containing your GitHub App's private key.
• WEBHOOK_SECRET is the secret name containing your GitHub App's webhook secret value.
• WEBHOOK_SECRET_VALUE is the value of your GitHub App's webhook secret.
• REGION is the region for your connection.
• CONNECTION_NAME is the name of your GitHub connection.
• URI is the URI of your connection. For example, https://my-github-enterprise-server.net.
• APP_ID is the ID of your GitHub App.
• APP_SLUG is the app slug. For example, https://github.com/settings/apps/{app-slug}.
• INSTALLATION_ID is the installation ID of your GitHub app. Your installation ID can be found in the URL of your Cloud Build GitHub App, https://github.com/settings/installations/{installation-id}.

You have now successfully created a GitHub Enterprise connection.

gcloud

After you have installed your GitHub app, complete the following steps to connect your GitHub Enterprise host programmatically using gcloud:

1. Store your secrets in Secret Manager:

   echo -n WEBHOOK_SECRET | gcloud secrets create mygheapp-webhook-secret --data-file=-
   # creating secret from the downloaded private key:
   gcloud secrets create mygheapp-private-key --data-file=PRIVATE_KEY_FILE
   

   Where:

   • WEBHOOK_SECRET is the string you created for your webhook secret.
   • PRIVATE_KEY_FILE is the file path to the private key you generated.

2. Grant access to the Cloud Build Service Agent to access your secrets:

   PROJECT_NUMBER=$(gcloud projects describe PROJECT_ID --format="value(projectNumber)")
   CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"
   gcloud secrets add-iam-policy-binding mygheapp-webhook-secret \
     --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
     --role="roles/secretmanager.secretAccessor"
   gcloud secrets add-iam-policy-binding mygheapp-private-key \
     --member="serviceAccount:CLOUD_BUILD_SERVICE_AGENT" \
     --role="roles/secretmanager.secretAccessor"
   

   Where:

   • PROJECT_ID is your Google Cloud project ID.
   • CLOUD_BUILD_SERVICE_AGENT is your Per-Product Per-Project account.

3. Create your GitHub Enterprise connection:

   gcloud builds connections create github-enterprise CONNECTION_NAME \
     --host-uri=HOST_URI \
     --app-id=APP_ID \
     --app-slug=APP_SLUG \
     --private-key-secret-version=projects/PROJECT_ID/secrets/mygheapp-private-key/versions/1 \
     --webhook-secret-secret-version=projects/PROJECT_ID/secrets/mygheapp-webhook-secret/versions/1 \
     --app-installation-id=INSTALLATION_ID \
     --region=REGION
   

   Where:

   • CONNECTION_NAME is the name of your connection.
   • HOST_URI is the URI of your GitHub Enterprise instance. For example, https://mmy-ghe-server.net.
   • APP_ID is the ID of your GitHub App.
   • APP_SLUG is the app slug. For example, https://my-ghe-server.net/settings/apps/app-slug.
   • PROJECT_ID is your Google Cloud project ID.
   • INSTALLATION_ID is the installation ID of your GitHub app. For example, https://my-ghe-server.net/settings/installations/installation-id
   • REGION is the region for your connection.

   If your GitHub Enterprise instance is in a private network, specify your Service Directory resource. You can also specify your CA certificate.

     --service-directory-service=projects/PROJECT_ID/locations/REGION/namespaces/NAMESPACE/services/SERVICE_NAME \
     --ssl-ca-file=SSL_CA_FILEPATH
   

   Where:

   • PROJECT_ID is your Google Cloud project ID.
   • REGION is the region for your connection.
   • NAMESPACE is the namespace of your service.
   • SERVICE_NAME is the name of your service in your namespace.
   • SSL_CA_FILEPATH is the file path to your CA certificate.

You have now successfully created a GitHub Enterprise connection.