Connect to a GitHub repository | Cloud Build | Google Cloud Documentation
Skip to main content Console English Deutsch Español Español – América Latina Français Indonesia Italiano Português Português – Brasil עברית 中文 – 简体 中文 – 繁體 日本語 한국어 Sign in Cloud Build Start free Home Documentation Application development Cloud Build Guides Connect to a GitHub repository Stay organized with collections Save and categorize content based on your preferences.
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, if any are not already enabled. Roles required to enable APIs To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role ( roles/owner ).
Otherwise, you can get this permission through the Service Usage Admin role ( roles/serviceusage.serviceUsageAdmin ). Learn how to grant roles . 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're 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 . Connect to 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 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. 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 . 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: 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. 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 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. Connect to a GitHub host programmatically To connect to a GitHub host programmatically, you must first configure the authentication token for the connection, and then create the GitHub connection in Cloud Build. Configure an authentication token To connect to a GitHub host programmatically, you must create a Cloud Build GitHub connection, including a secret for an authentication token.
You can acquire an authentication token in two ways: Create a personal access token in GitHub. Use a token from an existing Cloud Build GitHub connection. This method is helpful if your GitHub account has restrictions preventing the creation of Personal Access Tokens. In addition, if you reference this token when creating a connection from a script, you don't need to manually authenticate the connection using a web browser.
Personal access token Follow the steps to create a personal access token in the GitHub documentation. 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). Save the value of your personal access token.
You'll use it in a later step. Existing connection Run the following the command in gcloud CLI: gcloud builds connections describe CONNECTION_NAME --region = REGION Where: CONNECTION_NAME is the name of your GitHub host connection. REGION is the region for your trigger. In the command output, the value of the authorizerTokenSecretVersion is the ID of the secret containing the connection's authentication token. Copy this value and save it in a secure place.
You'll use the generated token in the following steps. Create the GitHub connection Create a GitHub connection by using Terraform or the gcloud CLI. 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. Configure your GitHub connection in Terraform. The following Terraform code sample shows shows a configuration that does the following: Configures the Terraform Google provider Creates a secret to store GitHub personal access tokens 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.polic
The rest of this page is on the live site.