Triggers file schema

This page explains the schema of the Secure Source Manager triggers file. For instructions on creating a triggers file, see Create a triggers file.

A triggers file contains instructions for Secure Source Manager to trigger the steps defined in a Cloud Build config file based on a push or pull request event in Secure Source Manager.

You can configure your branch protection rules to require a successful status check from specific triggers. To learn more about branch protection, read the Branch protection overview.

Structure of a triggers file

The triggers configuration file must be created in the default branch of your repository. You can write the triggers file using YAML syntax.

A triggers file has the following structure:

triggers:
- name: string
  project: string
  configFilePath: string
  eventType: string
  includedGitRefs: string
  ignoredGitRefs: string
  includedFiles: string
  ignoredFiles: string
  serviceAccount: string
  disabled: bool
  substitutions: map[string]string
- name: string
...

Each named section of the triggers file defines the Cloud Build configuration to use for the given event type in Secure Source Manager.

Triggers

A trigger specifies what Secure Source Manager event type you want to use to trigger the completion of the steps in a specific Cloud Build config file. You can also specify which branches are monitored for the specified event.

Use the name field in the triggers file to identify a trigger. Here's an example of the kind of configuration you might set in the triggers file:

triggers:
- name: presubmit-test
  project: my-project
  configFilePath: test.yaml
  eventType: pull_request
  includedGitRefs: ^main$
  ignoredGitRefs: .*log
  serviceAccount: projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
  includedFiles: .*
  ignoredFiles: my-file.txt
  disabled: false
- name: postsubmit-run
  project: my-project
  configFilePath: run.yaml
  eventType: push
  includedGitRefs: ^main$
  ignoredGitRefs: dev-branch
  serviceAccount: projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com
  disabled: false
  substitutions:
    _NODE_VERSION_1: v6.9.1
    REPO_NAME: dev

name

Required. Use the name field of the trigger to identify your trigger. Trigger names can only contain alphanumeric characters and dashes, and can't start or end with a dash. Trigger names must be less than 64 characters long.

project

Optional. Use the project field to identify the Google Cloud project where you enabled Cloud Build.

The default is the Secure Source Manager project.

configFilePath

Optional. Path to the Cloud Build configuration file.

The default is .cloudbuild/cloudbuild.yaml.

eventType

Optional. The event type to trigger on. Options are push for pushes to the selected branches or pull_request for pull requests to the selected branches.

The default is push.

includedGitRefs

Optional. A RE2 format regular expression matching the Git references that trigger a build.

The default is empty. An empty includedGitRefs filter field indicates that there are no restrictions.

If the Git reference isn't included in the ignoredGitRefs filter field, Secure Source Manager checks the includedGitRefs filter field. If the Git reference is in the includedGitRefs filter field, a build is triggered. If the includedGitRefs filter field isn't empty, and the Git reference isn't included in the includedGitRefs filter field, a build isn't triggered.

ignoredGitRefs

Optional. A RE2 format regular expression matching Git references that shouldn't trigger a build.

The default is empty. An empty ignoredGitRefs filter field indicates that there are no restrictions.

Secure Source Manager checks the ignoredGitRefs filter field first. If it's not empty and the Git reference matches the ignoredGitRefs filter field, a build isn't triggered.

serviceAccount

Required. The Cloud Build service account to use for the build.

Format: projects/PROJECT_ID/serviceAccounts/ACCOUNT

Replace the following:

  • PROJECT_ID: with the Google Cloud project ID where you created the service account.
  • ACCOUNT: with the email address or unique ID of the service account.

includedFiles

Optional. A RE2 format regular expression matching files that should trigger a build when changed.

If the changed files are not in the ignoredFiles filter field, and the changed files match the includedFiles filter field, a build is triggered.

The default is empty. An empty filter field indicates that there are no restrictions.

ignoredFiles

Optional. A RE2 format regular expression matching files that shouldn't trigger a build when changed.

If the ignoredFiles filter field isn't empty, commits that only include files that match the ignoredFiles filter field won't trigger a build. The default is empty. An empty filter indicates that there are no restrictions.

disabled

Optional. A boolean to set if the trigger is disabled or not. Values are true or false.

The default is false.

substitutions

Use substitutions in your triggers file to substitute specific variables at build time in your Cloud Build config file.

Substitutions must begin with an underscore, and can only contain uppercase-letters, underscores and numbers, or be one of the Secure Source Manager substitution variables.

Secure Source Manager provides the following default substitution variables:

  • TRIGGER_NAME: the name associated with the trigger.
  • COMMIT_SHA: the commit ID associated with the trigger.
  • REVISION_ID: the commit ID associated with the trigger.
  • SHORT_SHA: the first seven characters of COMMIT_SHA.
  • REPO_NAME: the name of the repository. For example: my-repo.
  • REPO_FULL_NAME: the resource path of the repository, for example: projects/my-project/locations/us-central/repositories/test-repo.
  • REF_NAME: the name of the branch or tag associated with the trigger.
  • TRIGGER_BUILD_CONFIG_PATH: the path to the build configuration file used during your build execution.

For information on how to include Secure Source Manager substitution variables in your Cloud Build configuration file, see Substituting variable values.

What's next