Connect to a GitHub repository (original) (raw)

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

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:
   1. Region: Select a region for your connection.
   2. Name: Enter a name for your connection.
7. 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 Repositoriespage.

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.

1. Log into your github.com account.
2. 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.
3. 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.
4. 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

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 Appon your GitHub account or in an organization you own.
2. 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.

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" iam.gserviceaccount.com members = ["serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudbuild."] } } 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 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 Appon your GitHub account or in an organization you own.
2. 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.
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.

1. Grant access to the Cloud Build Service Agent on the secret, whereSECRET_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="serviceiam.gserviceaccount.com-${PN}@gcp-sa-cloudbuild." gcloud secrets add-iam-policy-binding SECRET_NAME \ --member="serviceAccount:${CLOUD_BUILD_SERVICE_AGENT}" \ --role="roles/secretmanager.secretAccessor"
2. 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.

Connect a GitHub repository

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.

What's next

• Learn how to build repositories from GitHub.
• Learn how to perform blue-green deployments on Compute Engine.
• Learn how to specify additional repositories as dependencies to your build.