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.
- 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.
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.
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:
Region: Select a region for your connection.
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.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.
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.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 toCOMPLETE
, you have successfully installed the connection. Otherwise, theinstallationState
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
andread:user
. If your app is installed in an organization, make sure to also select theread: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.
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 value1234567
.
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
andread:user
. If your app is installed in an organization, make sure to also select theread: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.
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 value1234567
. - 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.
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:
- Connection: Select a connection from the drop-down menu.
Repository: Select a repository to link to your connection.
Repository Name: Enter a name for your repository.
- Generated: Select this option for Cloud Build to automatically generated repository names on your behalf for selected repositories.
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.