Connect to a GitHub repository

Console

To connect your GitHub repository to Cloud Build:

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

   Open the Repositories page

   You 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 as your source provider.

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

   • Region: Select a region for your connection.

   • Name: Enter a name for your connection.

7. Optional: If you want to manage the encryption keys used to encrypt the access tokens for your GitHub repositories, then go to the Encryption section and choose a Cloud Key Management Service key. For more information, see Enable customer-managed encryption keys for Secret Manager.

8. Click Connect.

   After you click the Connect button, you are asked to authorize the Cloud Build GitHub App to access your GitHub account. You may revoke access to the app by uninstalling or deleting the App from your host at any time.

   Cloud Build requests authorization of your GitHub user account and stores the resulting authorization token as a secret in Secret Manager in your project. The authorization token is used to validate access of your user account for the installation of the Cloud Build GitHub App and to the repositories linked. 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 are redirected to the Cloud Build Repositories page.

gcloud

To connect your GitHub host using gcloud, complete the following steps:

1. Enter the following command to initiate a connection to your GitHub repository:

    gcloud builds connections create github CONNECTION_NAME --region=REGION
   

   Where:

   • CONNECTION_NAME is a name for your connection as it will appear in Cloud Build.

   • REGION is the region for your trigger.

   After running the gcloud builds connections command, you see a link to authorize the Cloud Build GitHub App.

2. Log into your github.com account.

3. Follow the link to authorize the Cloud Build GitHub App.

   After authorizing the app, Cloud Build stores an authentication token as a secret in Secret Manager in your Google Cloud project. You can view your secrets on the Secret Manager page.

4. Install the Cloud Build GitHub App in your account or in an organization you own.

   Permit the installation using your GitHub account and select repository permissions when prompted.

5. Verify the installation of your GitHub connection by running the following command:

    gcloud builds connections describe CONNECTION_NAME --region=REGION
   

   Where:

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

   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.

Terraform

You can connect your GitHub host to Cloud Build using the Google Terraform provider by completing the following steps:

1. Install the Cloud Build GitHub App on your GitHub account or in an organization you own.

2. Create a personal access token in GitHub. We recommend generating this token using a dedicated GitHub robot account:

   • We strongly recommend creating a fine-grained Personal Access Token (PAT):

     • Set a short expiration date. A token without an expiration date is not recommended.
     • Choose the minimal permissions necessary for your setup.

   • If you must use a legacy/classic Personal Access Token as a fallback (which is less secure because it grants broad repository scopes), select the following OAuth scopes when prompted in GitHub:

   • repo to grant full access to public and private repositories.

   • read:user to grant access to read a user's profile data.

   • read:org for read-only access to organization membership and projects (if your app is installed in an organization).

3. After you generate your token, save it in a secure location. You will use this token in the subsequent steps.

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

• Configures the Terraform Google provider. If running the configuration from a deployment pipeline, configure the provider to use Workload Identity Federation with short-lived credentials.

• Creates a secret to express the GitHub Personal Access Token (PAT) and grants permissions to the Cloud Build Service Agent to access the secret.

• Creates a GitHub connection.

  // Configure the terraform google provider
  terraform {
    required_providers {
      google = {}
     }
  }
  
  // Create a secret containing the personal access token and grant permissions to the Service Agent
  resource "google_secret_manager_secret" "github_token_secret" {
      project = PROJECT_ID
      secret_id = SECRET_ID
  
      replication {
          auto {}
      }
  }
  
  resource "google_secret_manager_secret_version" "github_token_secret_version" {
      secret = google_secret_manager_secret.github_token_secret.id
      secret_data = GITHUB_PAT
  }
  
  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" {
    project = google_secret_manager_secret.github_token_secret.project
    secret_id = google_secret_manager_secret.github_token_secret.secret_id
    policy_data = data.google_iam_policy.serviceagent_secretAccessor.policy_data
  }
  
  // Create the GitHub connection
  resource "google_cloudbuildv2_connection" "my_connection" {
      project = PROJECT_ID
      location = REGION
      name = CONNECTION_NAME
  
      github_config {
          app_installation_id = INSTALLATION_ID
          authorizer_credential {
              oauth_token_secret_version = google_secret_manager_secret_version.github_token_secret_version.id
          }
      }
      depends_on = [google_secret_manager_secret_iam_policy.policy]
  }
  

Where:

• PROJECT_NUMBER is your Google Cloud project number.
• SECRET_ID is the ID of your token or secret in Secret Manager.
• GITHUB_PAT is the access token of the personal access token in GitHub.
• PROJECT_ID is your Google Cloud project ID.
• REGION is the region for your connection.
• CONNECTION_NAME is a name for your connection as it will appear in Cloud Build.
• INSTALLATION_ID is the installation ID of your Cloud Build GitHub app. Your installation ID can be found in the URL of your Cloud Build GitHub App. In the following URL, https://github.com/settings/installations/1234567, the installation ID is the numerical value 1234567.

gcloud

To connect your GitHub host using an existing token and installation ID obtained from a previous connection, complete the following steps:

1. Install the Cloud Build GitHub App on your GitHub account or in an organization you own.

2. Create a personal access token in GitHub. We recommend generating this token using a dedicated GitHub robot account:

   • We strongly recommend creating a fine-grained Personal Access Token (PAT):

     • Set a short expiration date. A token without an expiration date is not recommended.
     • Choose the minimal permissions necessary for your setup.

   • If you must use a legacy/classic Personal Access Token as a fallback (which is less secure because it grants broad repository scopes), select the following OAuth scopes when prompted in GitHub:

   • repo to grant full access to public and private repositories.

   • read:user to grant access to read a user's profile data.

   • read:org for read-only access to organization membership and projects (if your app is installed in an organization).

   After you generate your token, save it in a secure location. You will use this token in the subsequent steps.

3. Store your token in Secret Manager in your Google Cloud project by running the following command:

       echo -n TOKEN | gcloud secrets create SECRET_NAME --data-file=-
   

   Where:

   • TOKEN is your personal access token.
   • SECRET_NAME is the name you want to give to your secret in Secret Manager.

4. Grant access to the Cloud Build Service Agent on the secret, where SECRET_NAME is the name of your secret as stored in Secret Manager:

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

5. Create your GitHub connection:

     gcloud builds connections create github CONNECTION_NAME \
       --authorizer-token-secret-version=projects/PROJECT_ID/secrets/SECRET_NAME/versions/1  \
       --app-installation-id=INSTALLATION_ID --region=REGION
   

   Where:

   • CONNECTION_NAME is a name of your GitHub host connection in Cloud Build.
   • PROJECT_ID is your Google Cloud project ID.
   • SECRET_NAME is the name of your secret as stored in Secret Manager.
   • 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. In the following URL, https://github.com/settings/installations/1234567, the installation ID is the numerical value 1234567.
   • REGION is the region for of your connection.

Console

To connect a GitHub repository to a host connection, complete the following steps:

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

   Open the Repositories page

   You see the Repositories page.

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

3. Click Link Repositories to link repositories from your connection.

   You see the Connect Repositories panel.

4. In the Connect Repositories panel, enter the following information:

   1. Connection: Select a connection from the drop-down menu.

   2. Repository: Select a repository to link to your connection.

   3. Repository Name: Enter a name for your repository.

      1. Generated: Select this option for Cloud Build to automatically generated repository names on your behalf for selected repositories.

      2. Manual: Select this option to manually specify names for your selected repositories.

         If you select Manual, you can modify the names for your selected repositories in the Repository names section.

5. Click Link to link your repository to your connection.

gcloud

To add a GitHub repository to your connection, enter the following command:

   gcloud builds repositories create REPO_NAME \
     --remote-uri=REPO_URI \
     --connection=CONNECTION_NAME --region=REGION

Where:

• REPO_NAME is the name of your repository.
• REPO_URI is the link to your GitHub repository. For example, https://github.com/cloud-build/test-repo.git.
• CONNECTION_NAME is the name given to the GitHub Enterprise host connection created in Cloud Build from Connect to a GitHub host.
• REGION is the region for your connection.

Terraform

To add a GitHub repository to your connection, add the following code snippet to your Terraform configuration:

    resource "google_cloudbuildv2_repository" "my_repository" {
      project = "PROJECT_ID"
      location = "REGION"
      name = "REPO_NAME"
      parent_connection = google_cloudbuildv2_connection.my_connection.name
      remote_uri = "URI"
  }

Where:

• PROJECT_ID is your Google Cloud project ID.
• REPO_NAME is the name of your GitHub repository.
• REGION is the region for your connection.
• URI is the host URI of your repository. For example, https://github.com/myuser/myrepo.git.