Connect to a GitHub repository

This page explains how to connect a GitHub repository to Cloud Build. To learn more about Cloud Build repositories, see Cloud Build repositories.

Before you begin

Enable the Cloud Build and Secret Manager APIs.
Enable the APIs

Have your source code ready in a GitHub repository.
Have either a Dockerfile or a Cloud Build config file in your GitHub source repository.
If you are initially connecting your repository to Cloud Build, make sure you have admin-level permissions on your repository. To learn more about GitHub repository permissions, see Repository permission levels for an organization.
To use gcloud commands on this page, install the Google Cloud CLI.

Note: If you've installed gcloud CLI previously, make sure you have the latest available version by running gcloud components update.

Required IAM permissions

To connect your GitHub 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"

Connecting a GitHub host

Console

To connect your GitHub repository to Cloud Build:

Open the Repositories page in the Google Cloud console.

Open the Repositories page

You will see the Repositories page.
In the project selector in the top bar, select your Google Cloud project.
At the top of the page, select the 2nd gen tab.
Click Create host connection to connect a new host to Cloud Build.
On the left panel, select GitHub as your source provider.
In the Configure 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.
Click Connect.

After you click the Connect button, you will be 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.

Note: This authentication can be used to create additional connections in the same project. We recommend using a robot account, or an account shared by your team, instead of a personal GitHub account to keep your connections secure.

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

You have now successfully created a GitHub connection.

gcloud

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

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 the name of your connection.
- REGION is the region for your trigger.
  
  Note: You must specify a region. Your connection cannot exist globally.
After running the gcloud builds connections command, you will see a link to authorize the Cloud Build GitHub App.
Log into your github.com account.

Note: This authentication can be used to create additional connections in the same project. We recommend using a robot account, or an account shared by your team, instead of a personal GitHub account to keep your connections secure.
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.
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.
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 connection.
- 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.

You have now successfully created a GitHub connection.

Connecting a GitHub host programmatically

Terraform

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

Install the Cloud Build GitHub App on your GitHub account or in an organization you own.
Create a personal access token.

Make sure to set your token to have no expiration date and select the following permissions when prompted in GitHub: repo and read:user. If your app is installed in an organization, make sure to also select the read:org permission.

After you generate your personal access token, save your generated token in a secure place. You will use the generated token in the following steps.

Note: If you have an authentication token stored in a secret from a previously created connection, you can use that same secret for the new connection.

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

Configures the Terraform Google provider
Creates a secret to store GitHub personal access tokens to grant 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 ID of your personal access token in GitHub.
PROJECT_ID is your Google Cloud project ID.
REGION is the region for your connection.
CONNECTION_NAME is the name of your GitHub connection.
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.

You have now successfully created a GitHub connection.

gcloud

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

Install the Cloud Build GitHub App on your GitHub account or in an organization you own.
Create a personal access token.

Make sure to set your token to have no expiration date and select the following permissions when prompted in GitHub: repo and read:user. If your app is installed in an organization, make sure to also select the read:org permission.

After you generate your personal access token, save your generated token in a secure place. You will use the generated token in the following steps.

Note: If you have an authentication token stored in a secret from a previously created connection, you can use that same secret for the new connection.
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.

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"

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 the name of your connection.
- 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.

You have now successfully created a GitHub connection.

Connecting a GitHub repository

Console

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

Open the Repositories page in the Google Cloud console.

Open the Repositories page

You will see the Repositories page.
At the top of the page, select the 2nd gen tab.
Click Link Repositories to link repositories from your connection.

You will see the Connect Repositories panel.
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.
Click Link to link your repository to your connection.

You have now successfully linked your GitHub 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 of your connection.
REGION is the region for your connection.

You have now linked a repository to your GitHub 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 repo.
REGION is the region for your connection.
URI is the host URI of your repository. For example, https://github.com/myuser/myrepo.git.

You have now linked a repository to your GitHub connection.

What's next

Learn how to build repositories from GitHub.
Learn how to perform blue/green deployments on Compute Engine.