Console

To connect your GitHub Enterprise host to Cloud Build:

1. Open theRepositories page in the Google Cloud console.

   Open the Repositories page

   You will see theRepositories page.

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

3. At the top of the page, select the2nd gen tab.

4. ClickCreate host connection to connect a new host to Cloud Build.

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

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

   1. Region: Select a region for your connection.

      Note: You must specify a region. Your connection cannot exist globally.

   2. Name: Enter a name for your connection.

7. In theHost 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.

      Note: Your certificate must not exceed 10 KB in size and should be inPEM format (.pem,.cer, or.crt). If this section is left blank,adefault set of certificates will be used in place.

   3. UnderConnection 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. UnderService Directory service, selection the location for your service:

         • In projectyour-project
         • In another project
         • Enter manually

         1. If you selectIn another project orEnter manually, enter thefollowing 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 specifiedfor 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. ClickConnect.

   After clicking theConnect button, you will be asked to create a GitHub App in yourGitHub Enterprise host and install the app in a user account or organization. Anauthentication token from your GitHub Enterprise host will be created and stored in thisproject as a Secret Manager secret. You may revoke access by uninstalling ordeleting the GitHub app from your host at any time.

   Cloud Build stores the authentication data of the createdGitHub 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 APIof the Enterprise Server. The webhook secret is used to validate theevents sent from the server to Cloud Build. The Cloud BuildService Agent account (service-{projectNumber}@gcp-sa-cloudbuild.iam.gserviceaccount.com)is used to access your secret. To view your secret,seeList secrets and view secret details.

   After authorizing the Cloud Build GitHub App, you will beredirected to the Cloud BuildRepositoriespage.

gcloud

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

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

   gcloudbuildsconnectionscreategithub-enterpriseCONNECTION_NAME\--host-uri=HOST_URI--region=REGION

   Where:

   • CONNECTION_NAME is a name for your GitHub Enterprise host connection in Cloud Build.
   • HOST_URI is the URI of your GitHub Enterprise instance. For example,https://mmy-ghe-server.net.
   • REGION is theregion for your connection.

   If your GitHub Enterprise instance is in a private network, specify yourService 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 theregion 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 path to your CA certificate.

   After running thegcloud builds connections... command, you willreceive a link to install the Cloud Build GitHub app.

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

3. Enter the following command to verify your connection:

   gcloudbuildsconnectionsdescribeCONNECTION_NAME--region=REGION

   Where:

   • CONNECTION_NAME is the name of your GitHub Enterprise host connection in Cloud Build.
   • REGION is theregion for your connection.

   If theinstallationState field is set toCOMPLETE, you have successfullyinstalled the connection. Otherwise, theinstallationState field providesa link for additional steps required.

Terraform

Once you have installed your GitHub app, you can connect your GitHub Enterprise hostto 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 providerterraform{required_providers{google={}}}// create Secrets and grant permissions to the Service Agentresource"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.idsecret_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.idsecret_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.projectsecret_id=google_secret_manager_secret.private-key-secret.secret_idpolicy_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.projectsecret_id=google_secret_manager_secret.webhook-secret-secret.secret_idpolicy_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.idwebhook_secret_secret_version=google_secret_manager_secret_version.webhook-secret-secret-version.idapp_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 theregion for your connection.
• CONNECTION_NAME is a name for your GitHub Enterprise host connection in Cloud Build.
• 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. Yourinstallation ID can be found in the URL of your Cloud BuildGitHub App,https://github.com/settings/installations/{installation-id}.

gcloud

After you have installed your GitHub app, complete the following steps toconnect your GitHub Enterprise host programmatically usinggcloud:

1. Store your secrets in Secret Manager:

   echo-nWEBHOOK_SECRET|gcloudsecretscreatemygheapp-webhook-secret--data-file=-# creating secret from the downloaded private key:gcloudsecretscreatemygheapp-private-key--data-file=PRIVATE_KEY_FILE

   Where:

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

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

   PROJECT_NUMBER=$(gcloudprojectsdescribePROJECT_ID--format="value(projectNumber)")CLOUD_BUILD_SERVICE_AGENT="service-$PROJECT_NUMBER@gcp-sa-cloudbuild.iam.gserviceaccount.com"gcloudsecretsadd-iam-policy-bindingmygheapp-webhook-secret\--member="serviceAccount:$CLOUD_BUILD_SERVICE_AGENT" \--role="roles/secretmanager.secretAccessor"gcloudsecretsadd-iam-policy-bindingmygheapp-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:

   gcloudbuildsconnectionscreategithub-enterpriseCONNECTION_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 a name for your GitHub Enterprise host connection in Cloud Build.
   • 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 theregion for your connection.

   If your GitHub Enterprise instance is in a private network, specify yourService 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 theregion 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 path to your CA certificate.