Create and manage build triggers

A Cloud Build trigger automatically starts a build whenever you make any changes to your source code. You can configure the trigger to build your code on any changes to the source repository or only changes that match certain criteria.

This page explains how to connect to source repositories such as GitHub and Bitbucket, and create build triggers to build the code in the repositories.

Before you begin

• Enable the Cloud Build API.

  Enable the API

• You need to have the Cloud Build Editor (roles/cloudbuild.builds.editor) role in your project to create triggers.
• You need source code in Cloud Source Repositories, GitHub, or Bitbucket.
• You need either a Dockerfile or a Cloud Build config file.

Caution: Effective June 17, 2024, Cloud Source Repositories isn't available to new customers. If your organization hasn't previously used Cloud Source Repositories, you can't enable the API or use Cloud Source Repositories. New projects not connected to an organization can't enable the Cloud Source Repositories API. Organizations that have used Cloud Source Repositories prior to June 17, 2024 are not affected by this change.

Connect to source repositories

You must first connect Cloud Build to your source repository before building the code in that repository. Your repositories in Cloud Source Repositories are connected to Cloud Build by default. You can directly create triggers for your repositories in Cloud Source Repositories without manually connecting to them.

If you are connecting an external repository, such as one hosted on GitHub or Bitbucket, you will need admin-level permissions on the repository to initially connect your repository to Cloud Build. Admin permissions are not required to create triggers in a repository that is already connected to Cloud Build.

Complete the following steps to connect to GitHub or Bitbucket:

1. Open the Triggers page in the Google Cloud console.

   Open the triggers page

2. Select your project and click Open.

3. Select the region where you would like to create your trigger from the Region drop-down menu.

   Note: If you select global as your region, default pools are used to run your build. Otherwise, a private pool in the region of your trigger is used to run your build. You must specify the private pool in your build config file or through build arguments.

4. Click Connect Repository.

5. Select the repository where you've stored your source code.

   If you select GitHub (mirrored) or Bitbucket (mirrored) as your source repository, Cloud Build mirrors your repository in Cloud Source Repositories and uses the mirrored repository for all its operations.

6. Click Continue.

7. Authenticate to your source repository with your username and password.

8. From the list of available repositories, select the repository, then click Connect.

   For external repositories, such as GitHub and Bitbucket, you must have owner-level permissions for the Google Cloud project with which you're working.

9. Click Create a trigger to continue creating a build trigger to automate builds for the source code in the repository, or click Done.

Creating a build trigger

Console

1. Open the Triggers page in the Google Cloud console.

   Open the Triggers page

2. Select your project from the project selector drop-down menu at the top of the page.

3. Click Open.

4. Click Create trigger.

5. Enter the following trigger settings:

   • Name: Enter a name for your trigger.

   • Region: Select the region for your trigger.

     If the build config file associated with your trigger specifies a private pool, the region you select for your trigger must match the region of the private pool.

     If you select global as your region, Cloud Build uses the region specified in your build config file to run your build. This can either be the region of the private pool, if you specify a private pool in your build config file, or the global default pool if you don't specify a private pool.

   • Description (optional): Enter a description for your trigger.

   • Event: Select the repository event to invoke your trigger.

     • Push to a branch: Set your trigger to start a build on commits to a particular branch.

     • Push new tag: Set your trigger to start a build on commits that contain a particular tag.

     • Pull request: Set your trigger to start a build on commits to a pull request.

       Note: Whether based on branch commits or tag commits, builds are only invoked on pushes to the remote origin -- not on local changes, pre-submits, or pull requests.

   • Source: Select 1st generation or 2nd generation as your source. You can only connect repositories from GitHub and GitHub Enterprise when selecting 2nd generation as your source. To learn more, see Cloud Build repositories.

     Note: The region of your repository must match the region of your trigger. If your source is a Cloud Source Repository, your repository is not connected to a particular region, but to your project.
     • Repository: From the list of available repositories, select the desired repository. To connect a new repository, see Connecting to source repositories.
     Note: If you rename your repository following trigger creation, you need to manually update the repository name in your trigger. Currently, Cloud Build does not automatically redirect build requests from your trigger if a repository name is updated.

     • Branch or Tag: Specify a regular expression with the branch or tag value to match. Forward slashes (/) cannot be used in tags. For more information on acceptable regular expression syntax, see RE2 syntax.

       When your build executes, Cloud Build copies the contents of your repository to /workspace, the default working directory for Cloud Build. Learn more about working directories on the Build configuration overview page.

       To only allow builds from specific sources, set an organization policy for allowed integrations (constraints/cloudbuild.allowedIntegrations) to deny interaction with the source defined in your trigger. The organization policy overrides the trigger and your build is not executed. To learn more, see Gate builds on organization policy for your project.

     Note: You will get suggestions based on the branches or tags present in your repository. If you use 2nd gen repository that has more than 500 branches or tags some of them will be missing from the list. You can specify a regular expression manually.

   • Included files (optional): Changes affecting at least one of these files will invoke a build. You can use glob strings to specify multiple files with wildcard characters. Acceptable wildcard characters include the characters supported by Go Match, **, and alternation.

     Note: ** is a recursive version of * which matches all files and directories in the selected directory and its subdirectories. For example, the pattern src/* will match src/code.py, but will ignore src/sub/code.py whereas src/** will match both.

   • Ignored files (optional): Changes only affecting ignored files won't invoke a build. You can use glob strings to specify multiple files with wildcard characters. Acceptable wildcard characters include the characters supported by Go Match, **, and alternation.

     Note: Glob strings don't allow for substitution variables in included files and ignored files.

     If you specify a file in both Included files and Ignored files, changes to that file will not invoke a build. Say you specify **/README.md in Ignored files to ignore README.md in any directory, and specify src/* in Included files to start a build on changes to any file in the folder src/. Now if you make a change to src/README.md, Cloud Build won't start a build. Each time you push a change to your source, Cloud Build looks through your changed files for included and ignored files to determine whether a build should be invoked:

     • If you push a change to your repository on an existing branch, Cloud Build looks at the files changed between the commit you just pushed and the commit to which the branch previously pointed.
     • If your repository is Cloud Source Repository and you push a change to a newly created branch, then Cloud Build treats all the files in the repository as changed files.
     • If you delete a branch, Cloud Build does not start a build.
   Note: Included files and Ignored files can only be specified if you select Push to a branch or Push new tag as your Event.

   • Configuration: Select the build config file located in your remote repository or create an inline build config file to use for your build.

     • Type: Select the type of configuration to use for your build.
       • Cloud Build configuration file (yaml or json): Use a build config file for your configuration.
       • Dockerfile: Use a Dockerfile for your configuration.
       • Buildpacks: Use buildpacks for your configuration.

     • Location: Specify the location for your configuration.

       • Repository: If your config file is located in your remote repository, provide the location of your build config file, the Dockerfile directory, or the buildpacks directory. If your build config type is a Dockerfile or a buildpack, then you need to provide a name for the resulting image and optionally, a timeout for your build. When you've provided the Dockerfile or buildpack image name, you'll see a preview of the docker build or pack command that your build will execute.
       • Buildpack environment variables (optional): If you selected buildpacks as your configuration type, click Add pack environment variable to specify your buildpack environment variables and values. To learn more about buildpack environment variables, see Environment variables.

       • Inline: If you selected Cloud Build configuration file (yaml or json) as your configuration option, you can specify your build config inline. Click Open Editor to write your build config file in the Google Cloud console using YAML or JSON syntax. Click Done to save your build config.

         Note: Inline build configuration support is not available for Dockerfile or buildpacks.

   • Use private pool: This field appears if you selected Dockerfile as your Configuration option. Select this checkbox if you're running your build in a private pool.

   • Private pool: If you selected Use private pool, specify the resource name of the private pool of the form projects/WORKERPOOL_PROJECT_ID/locations/REGION/workerPools/WORKERPOOL_ID.

   • Substitution variables (optional): If you selected the Cloud Build config file as your build config option, you can choose to define trigger-specific substitution variables using this field. For example, say you're creating multiple triggers where each trigger deploys your app to a specific environment. You can specify that your app is deployed to an environment in your build config file and then use this field to define substitution variables specifying which environment this trigger should deploy to. For information on specifying substitution values in build config files, see Substituting variable values.

   • Approval (optional): Check the box to require approval before your build executes.

   • Service account: Select the service account to use when invoking your trigger. If you don't select a service account, the Cloud Build legacy service account is used if it is available to your project.

     Note: Only the service account specified on your trigger will be used for builds executed by triggers. If you specified a service account in your build config, it will be ignored during build execution when using triggers.

6. Click Create to save your build trigger.

gcloud

To create a trigger if your source code is in Cloud Source Repositories:

    gcloud builds triggers create cloud-source-repositories \
    --repo=REPO_NAME \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval

Where:

• REPO_NAME is the name of your repository.
• BRANCH_PATTERN is the branch name in your repository to invoke the build on.
• TAG_PATTERN is the tag name in your repository to invoke the build on.
• BUILD_CONFIG_FILE is the path to your build configuration file.
• SERVICE_ACCOUNT is the email associated with your service account. If you don't include this flag, the Cloud Build legacy service account is used if it is available to your project.

Note: Only the service account specified in the gcloud builds triggers create command is used for builds invoked with triggers. Build triggers ignore the service account specified in the build config file.

• Optional: --require-approval is the flag to include to configure your trigger to require approval.

For a complete list of flags, see the gcloud reference for how to create triggers for Cloud Source Repositories.

To create a trigger if your source code is in GitHub:

    gcloud builds triggers create github \
    --region=REGION \
    --repo-name=REPO_NAME \
    --repo-owner=REPO_OWNER \
    --branch-pattern=BRANCH_PATTERN \ # or --tag-pattern=TAG_PATTERN
    --build-config=BUILD_CONFIG_FILE \
    --service-account=SERVICE_ACCOUNT \
    --require-approval
    --include-logs-with-status

Where:

• REGION is the region for your trigger.
• REPO_NAME is the name of your repository.
• REPO_OWNER is the username of the repository owner.
• BRANCH_PATTERN is the branch name in your repository to invoke the build on.
• TAG_PATTERN is the tag name in your repository to invoke the build on.
• BUILD_CONFIG_FILE is the path to your build configuration file.
• SERVICE_ACCOUNT is the email associated with your service account. If you don't include this flag, the Cloud Build legacy service account is used if it is available to your project.
• Optional: --require-approval is the flag to include to configure your trigger to require approval.
• Optional: --include-logs-with-status is a flag you can specify to show build logs for your repositories. This flag is supported for builds from GitHub and GitHub Enterprise repositories.

Note: You can only use the --include-logs-with-status flag when creating a GitHub or GitHub Enterprise trigger using gcloud. Cloud Build doesn't support creating a trigger using the Google Cloud console.

For a complete list of flags, see the gcloud reference for how to create triggers for GitHub.

After you run the gcloud command to create a trigger using Cloud Source Repositories or GitHub, you should see an output similar to the following:

  NAME         CREATE_TIME                STATUS
  trigger-001  2019-10-30T20:45:03+00:00

Note: The trigger name is automatically generated for you. You can change the name of your trigger with the Google Cloud console.

Testing a build trigger

To manually test a build trigger:

1. Open the Triggers page in the Google Cloud console.

   Open the triggers page

2. Locate your trigger in the list and then click Run trigger.

Skipping a build trigger

In some cases, you may want to make a change to your source code but you don't want to invoke a build. For example, you might not want to invoke a build when you update documentation or configuration files.

In such scenarios, you can include [skip ci] or [ci skip] in the commit message, and a build will not be invoked.

If you want to run a build on that commit later, use the Run trigger button in the Triggers page.

Including the repository history in a build

To build your source on a Git repository, Cloud Build performs a shallow clone of the repository. This means that only the single commit that started the build is checked out in the workspace to build. Cloud Build does not check out any other branches or history. This is done for efficiency, so that builds don't have to wait to fetch the whole repository and history just to build a single commit.

If you want to include more of your repo's history in the build, add a build step in your build config file to "unshallow" the clone. For example:

steps:
- name: gcr.io/cloud-builders/git
  args: ['fetch', '--unshallow']
...

Note: If your source is in a private Git repository, you will need to store your credentials securely using Secret Manager in order to access git commands such as the previous command to "unshallow" the clone of your repository. For further instructions, see Accessing private GitHub repositories.

For more information on git fetch, see git reference. For instructions on writing a build config file, see Build config overview.

Resubmitting a build for approval

If your build has been rejected, you can resubmit your build for approval by following these steps in the Google Cloud console:

1. Open the Cloud Build History page in the Google Cloud console.

   Open the Cloud Build History page

2. Click the build ID of the build you'd like to resubmit for approval.

3. Click Rebuild at the top of the page to resubmit your build for approval.

Your build will start when a user with permissions approves your build. To learn more about Cloud Build approvals, see Gate builds on approval.

Updating a build trigger

Console

1. Open the Triggers page in the Google Cloud console.

   Open the Build triggers page

2. Select your project from the project selector drop-down menu at the top of the page.

3. Click Open.

4. Locate the row with the trigger you would like to update.

5. Click the menu (vertical ellipses) located at the right end of the row.

6. Select Edit.

Note: You can update all fields associated with your trigger using the Google Cloud console except showing build logs. See the gcloud instructions for how to update a build trigger to show or hide build logs for GitHub or GitHub Enterprise triggers.

gcloud

To update a trigger:

1. Export the trigger you would like to update:

    gcloud beta builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
   

   Where:

   • TRIGGER_NAME is the name of your trigger.
   • EXPORT_PATH is the path you want to export your trigger to. For example, you can specify your path as examples/trigger.yaml. Note that the filename for your trigger should have the .yaml extension.

2. Open the file containing your exported trigger.

   Your file will look similar to the following:

    createTime: '2022-05-26T21:56:11.830784153Z'
    filename: cloudbuild.yaml
    github:
      name: cloud-build-example
      owner: main
      push:
        branch: master
    id: 86201062-3b14-4b6a-a2fb-4ee924e8b1dd
    # remove field name and value to not show build logs
    includeBuildLogs: INCLUDE_BUILD_LOGS_WITH_STATUS
    name: trigger-001
   

3. Manually edit your file to update your trigger.

   To view fields you can add or remove from your trigger, see the trigger resource.

4. Save your file.

5. Import your trigger:

    gcloud builds triggers import --source=IMPORT_PATH
   

   Where:

   • IMPORT_PATH is the path of your trigger that you would like to import.

Your build trigger is now updated.

Disabling a build trigger

Console

1. Open the Triggers page in the Google Cloud console.

   Open the Build triggers page

2. Select your project from the project selector drop-down menu at the top of the page.

3. Click Open.

4. Locate the row with the trigger you would like to disable.

5. Click the menu (vertical ellipses) located at the right end of the row.

6. Select Disable.

gcloud

To disable a trigger:

1. Export the trigger you would like to disable:

    gcloud beta builds triggers export TRIGGER_NAME --destination=EXPORT_PATH
   

   Where:

   • TRIGGER_NAME is the name of your trigger.
   • EXPORT_PATH is the path you want to export your trigger to. For example, you can specify your path as examples/trigger.yaml. Note that the filename for your trigger should have the .yaml extension.

2. Open the file containing your exported trigger.

   Your file will look similar to the following:

    createTime: '2020-02-21T20:02:50.215599013Z'
    description: Push to any branch
    filename: cloudbuild.yaml
    github:
      name: example-repo-name
      owner: example-owner
      push:
        branch: .*
    id: example-id
    name: Push-to-any-branch
    tags:
    - github-default-push-trigger
   

3. Add the disabled field to the end of your file and set the value to True.

    disabled: True
   

4. Save your file.

5. Import your trigger:

    gcloud builds triggers import --source=IMPORT_PATH
   

   Where:

   • IMPORT_PATH is the path of your trigger that you would like to import.

Your build trigger is now disabled.

Note: Disabling a trigger using gcloud commands may not work if you don't have a build configuration file associated with your trigger.

Disabling a trigger does not delete the trigger. To delete a trigger, see Deleting a build trigger. A trigger can be re-enabled by changing the status to Enabled.

Deleting a build trigger

Console

1. Open the Triggers page in the Google Cloud console.

   Open the Build triggers page

2. Select your project from the project selector drop-down menu at the top of the page.

3. Click Open.

4. Locate the row with the trigger you would like to delete.

5. Click the menu (vertical ellipses) located at the right end of the row.

6. Select Delete.

gcloud

To delete a trigger, run the following command:

  gcloud builds triggers delete TRIGGER_NAME

Where:

• TRIGGER_NAME is the name of your trigger.

For a complete list of flags, see the gcloud reference for how to delete triggers.

Security implications of build triggers

Note: To improve the default security posture of your projects, Cloud Build will introduce changes that will require you to explicitly select a service account when you create a trigger in new projects. For more information see Cloud Build default service account change.

The service account configured for a build trigger can provide elevated build-time permissions to users who employ triggers to invoke a build. This applies to both your Cloud Build default service account and user-specified service accounts. Keep in mind the following security implications when using build triggers:

• A user with no access to your Cloud project, but with write access to the repository associated with build triggers in the project will have permissions to change the code being built.
• If you're using GitHub pull request triggers, any user with read access to the repository can submit a pull request, which may execute a build that includes changes to the code in the pull request. To learn how you can disable this behavior for GitHub pull request triggers, see Creating GitHub triggers.

It's a good security practice to create a service account with only the required roles for your trigger. To learn more see Configure user-specified-service accounts. To learn more about the Cloud Build legacy service account and its associated permissions, see Cloud Build service account.

What's next

• Learn how to start builds manually or set up deployments that require manual invocation by manually building code in source repositories.
• Learn how to create GitHub triggers.
• Learn how to automate builds in response to Pub/Sub events.
• Learn how to automate builds in response to webhook events.
• Learn how to view build results for build triggers.
• Learn how to perform blue-green deployments on Compute Engine.
• Learn how to troubleshoot build errors.