Automate builds on repository events

Linux

Preview

This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

For information about access to this release, see the access request page.

You can configure automated Image Builder pipelines that run whenever you push configuration changes to your Git repository such as pushing to main. Automating builds on repository events ensures that Cloud Build immediately validates, builds, and publishes your custom OS images to Compute Engine and Artifact Registry upon code review or merge.

Before you begin

• Complete the environment setup steps in Prepare your environment.
• If you intend to deploy your pipeline by using Terraform or automate builds from a repository, connect your GitHub, GitLab, or Bitbucket repository by using Cloud Build repositories (2nd gen) or Developer Connect connection links.
• Ensure your repository contains your cloudbuild.yaml orchestration file, your imagebuilder.yaml recipe file, and any referenced build scripts.
• If you plan to use Terraform, install the Terraform CLI version 1.3 or later.
• If you haven't already, set up authentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  gcloud

  1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  Terraform

  To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  1. Install the Google Cloud CLI.

  2. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  3. If you're using a local shell, then create local authentication credentials for your user account:

     gcloud auth application-default login

     You don't need to do this if you're using Cloud Shell.

     If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  For more information, see Set up authentication for a local development environment.

Required roles

To get the permissions that you need to create repository event triggers, ask your administrator to grant you the following IAM roles on your project:

• Cloud Build Editor (roles/cloudbuild.builds.editor)
• Service Account User (roles/iam.serviceAccountUser)

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Configure repository automation

You can configure repository event triggers by using either the gcloud CLI or Terraform. Select one of the following tabs to configure repository triggers:

gcloud

You can create an automated repository trigger by using the gcloud builds triggers create command and pointing directly to your connected 2nd-gen repository link (--repository).

gcloud builds triggers create repository \
    --name="TRIGGER_NAME" \
    --repository="projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME" \
    --branch-pattern="^main$" \
    --build-config="CLOUDBUILD_YAML_PATH" \
    --service-account="projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL" \
    --substitutions="_GCS_WORKDIR=gs://STAGING_BUCKET/workdir/,_IMAGE_BUILDER_CONFIG_PATH=RECIPE_PATH,_SERVICE_ACCOUNT=projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL,_IMAGE_OUTPUT_PATH=image-builder/binaryOut" \
    --region=REGION \
    --project=PROJECT_ID

Replace the following:

• TRIGGER_NAME: the name for your trigger, for example, git-push-custom-os-builder.
• PROJECT_ID: your project ID.
• REGION: the region where your repository connection is hosted, for example, us-central1.
• CONNECTION_NAME: the name of your Developer Connect connection, for example, github-connection.
• REPO_NAME: the linked Git repository name.
• CLOUDBUILD_YAML_PATH: the relative path to cloudbuild.yaml in your local directory.
• SERVICE_ACCOUNT_EMAIL: the exact email address of your build service account.
• STAGING_BUCKET: your Cloud Storage staging workdir bucket name.
• RECIPE_PATH: the relative path to imagebuilder.yaml in your repository.

Terraform

To configure an automated repository trigger by using Terraform, complete the following steps:

1. Add the trigger resource to your main.tf configuration file:

   resource "google_cloudbuild_trigger" "repository_trigger" {
     name        = "TRIGGER_NAME"
     location    = "REGION"
     project     = "PROJECT_ID"
     description = "Triggers custom OS image builds on repository push events"
   
     repository_event_config {
       repository = "projects/PROJECT_ID/locations/REGION/connections/CONNECTION_NAME/repositories/REPO_NAME"
       push {
         branch = "^main$"
       }
     }
   
     filename = "CLOUDBUILD_YAML_PATH"
   
     substitutions = {
       _GCS_WORKDIR               = "gs://STAGING_BUCKET/workdir/"
       _IMAGE_BUILDER_CONFIG_PATH = "RECIPE_PATH"
       _SERVICE_ACCOUNT           = "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT_EMAIL"
     }
   }
   

   Replace the following:

   • TRIGGER_NAME: the name for your trigger, for example, git-push-custom-os-builder.
   • PROJECT_ID: your project ID.
   • REGION: the Google Cloud region where your repository connection is hosted, for example, us-central1.
   • CONNECTION_NAME: the name of your Developer Connect connection, for example, github-connection.
   • REPO_NAME: the linked Git repository name.
   • CLOUDBUILD_YAML_PATH: the relative path to cloudbuild.yaml in your local directory.
   • STAGING_BUCKET: your Cloud Storage staging bucket name.
   • RECIPE_PATH: the relative path to imagebuilder.yaml in your repository.
   • SERVICE_ACCOUNT_EMAIL: the email address of your build service account.

2. Deploy the updated Terraform configuration:

   terraform plan
   terraform apply
   

   To review the complete multi-file Terraform infrastructure project structure, see Create and manage pipelines using Terraform.

What's next

• Learn how to Schedule custom OS image builds periodically for security patching by using Cloud Scheduler.
• Explore Supported customization actions (Shell, FileCopy, UpdateKernelCommandLine, InstallGPU).