Connect to a GitHub Enterprise host (original) (raw)

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

Required IAM permissions

To connect your GitHub Enterprise host, grant the Cloud Build Connection Admin (roles/cloudbuild.connectionAdmin) 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.

To create connections using gcloud installation steps, grant the Secret Manager Admin role (roles/secretmanager.admin) to the Cloud Build Service Agent by running the following command in your Google Cloud project:

      PN=$(gcloud projects describe ${PROJECT_ID} --format="value(projectNumber)")
      CLOUD_BUILD_SERVICE_AGENT="service-${PN}@gcp-sa-cloudbuild.iam.gserviceaccount.com"
       gcloud projects add-iam-policy-binding ${PROJECT_ID} \
         --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \
         --role="roles/secretmanager.admin"

If your GitHub Enterprise instance is hosted in a private network, see Build repositories from GitHub Enterprise in a private network to learn about additional IAM roles required prior to host connection.

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 Repositoriespage.

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:
gcloud builds connections create github-enterprise CONNECTION_NAME \  
  --host-uri=HOST_URI --region=REGION

Where: 

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

Where:

  1. Follow the link returned in the previous step to create and install the Cloud Build GitHub App on your enterprise server.
  2. Enter the following command to verify your connection:
gcloud builds connections describe CONNECTION_NAME --region=REGION

Where:

Connect to a GitHub Enterprise host programmatically

To connect your GitHub Enterprise host programmatically to Cloud Build, you must install the GitHub app by completing the following steps:

  1. Register a new GitHub app. For example, you may register a new GitHub app at https://my-ghe-server.net/settings/apps/new.
  2. Complete the fields on the page:
    1. GitHub App Name: Enter a name for your app.
    2. Homepage URL: Enter a URL for your GitHub Enterprise Server.
    3. Clear the box for Expire user authorization tokens.
    4. In the Webhook section, complete the following steps:
      • Active: Check the box to activate your webook.
      • Webhook URL: Enter your webhook URL. For example, https://cloudbuild.googleapis.com/v2/projects/{PROJECT_NUMBER}/locations/{REGION}/connections:processWebhook. The region in the webhook URL must match the region of your connection.
      • Webhook secret: Enter a randomly generated string and take note of it.
    5. In the Permissions section, specify the following permissions:
      • Repository permissions:
        * Checks: Read and write
        * Contents: Read and write
        * Issues: Read-only
        * Metadata Read-only
        * Commit statuses: Read-only
        * Pull requests: Read-only
    6. In the Subscribe to events section, check the following boxes:
      • Check run
      • Check suite
      • Commit comment
      • Issue comment
      • Pull request
      • Pull request review comment
      • Push
      • Repository
    7. Check the box for Any account to allow your GitHub app to be installed by any user or organization.
  3. Click Create GitHub app to create your GitHub app.
    One you click Create GitHub app, you will be redirected to your app page. Take note of your App ID and the App slug. The App slug can be found in the last segment of the URL of the page. For example, https://my-ghe-server.net/settings/apps/{app-slug}
  4. In the Private keys section, click Generate a private key.
    Store the downloaded file in a secure place.
  5. In the left pane, select Install App.
    Select the user or organization where you want to install the app. After the app is installed, take note of the installation ID. The installation ID can be found in the last segment of the URL of the page. For example, https://my-ghe-server.net/settings/installations/{installation-id}.

After you have installed your GitHub app, complete the following steps to connect your GitHub Enterprise host programmatically using Terraform orgcloud.

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:

// 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:

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:

  1. 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:

  1. 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: 

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

Where:

Next steps