This page describes the steps to create a triggers YAML file inSecure Source Manager. A triggers file can be used to automate buildsbased on push and pull request events in a Secure Source Manager repository.

To learn about the fields you can include in a triggers file, readTriggers file schema.

Before you begin

1. Create a Secure Source Manager instance.
2. Create a Secure Source Manager repository.
3. Read theTriggers file schema to learn about thefields you can include in a triggers file.

Required roles

To get the permissions that you need to create a triggers file, ask your administrator to grant you the following IAM roles:

• Secure Source Manager Instance Accessor (roles/securesourcemanager.instanceAccessor) on the instance
• Secure Source Manager Repository Writer (roles/securesourcemanager.repoWriter) on the repository

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

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

Create a Cloud Build configuration file

Secure Source Manager triggers files require that you specify a buildconfiguration file for each trigger.

A build config file contains instructions for Cloud Build to performtasks based on your specifications. For example, your build config file cancontain instructions to build, package, and push Docker images.

Create your build configuration files in the branch or branches where you wantto build from. To create your build configuration files, follow the instructionsinCreate a build configuration file.

Create a triggers file

The triggers configuration file must be created in thedefault branch ofyour repository.

To create a triggers configuration file:

1. In your local repository or the Secure Source Manager web interface, switchto thedefault branch.

2. Create a file named.cloudbuild/triggers.yaml.

3. Configure your trigger in the.cloudbuild/triggers.yaml file:

   triggers:-name:TRIGGER_NAMEproject:PROJECT_IDconfigFilePath:CLOUD_BUILD_CONFIG_PATHeventType:EVENT_TYPEignoredGitRefs:IGNORED_GIT_REFSincludedGitRefs:INCLUDED_GIT_REFSserviceAccount:SERVICE_ACCOUNTincludedFiles:INCLUDED_FILESignoredFiles:IGNORED_FILESdisabled:DISABLED_BOOLsubstitutions:_VARIABLE_NAME:VARIABLE_VALUEOVERRIDE_VARIABLE_NAME:OVERRIDE_VARIABLE_VALUE

   Replace the following:

   • TRIGGER_NAME with a name for your trigger. Trigger namescan only contain alphanumeric characters and dashes, and can't start orend with a dash. Trigger names must be less than 64 characters long.
   • PROJECT_ID with the Google Cloud project ID where youenabled Cloud Build. This field is optional. The default is theSecure Source Manager project.
   • CLOUD_BUILD_CONFIG_PATH with the path to theCloud Build configuration file you want to use for this trigger.This field is optional. The default value is.cloudbuild/cloudbuild.yaml

   • EVENT_TYPE with the event type you want to trigger thebuild. Options are as follows:

     • push to trigger on push to the specified branch(es)
     • pull_request to trigger on a pull request to the specifiedbranch(es)

     This field is optional. The default value ispush.

   • INCLUDED_GIT_REFS with an optionalRE2 regular expression format matching theGit references that you want to trigger abuild. The default value is empty. An empty value indicates thereare no restrictions.

   • IGNORED_GIT_REFS with an optional regular expression usingthe RE2 regular expression format matchingthe Git references that you don't want totrigger a build. The default value is empty. An empty value indicatesthere are no restrictions. TheignoredGitRefs field is checked beforetheincludedGitRefs field. For more information on these fields, seeTriggers file schema.

   • SERVICE_ACCOUNT with theCloud Build service account to use for the build in theformatprojects/PROJECT_ID/serviceAccounts/ACCOUNT.ReplaceACCOUNT with the email address or unique ID of theservice account. As a best practice,configure a user-specified service account.The legacy Cloud Build service account can't be used due to itslimitations.

   • INCLUDED_FILES with an optional RE2 format regularexpression matching files you want to trigger a build.

     If any of the changed files don't match theignoredFiles filter field,and the changed files match theincludedFiles filter field, a build istriggered. The default value is empty. An empty value indicates thereare no restrictions.

   • IGNORED_FILES with an optional RE2 format regularexpression matching files you don't want to trigger a build.

     If all changed files in a commit match this filter field, a build isn'ttriggered. The defaultvalue is empty. An empty value indicates there are no restrictions.

   • DISABLED_BOOL withtrue to disable the trigger, orfalse to enable the trigger. This field is optional. The default valueisfalse.

   • VARIABLE_NAME with the name of a variable you want tointroduce in your triggers file.

   • VARIABLE_VALUE with the value of the variable.

   • OVERRIDE_VARIABLE_NAME with the Secure Source Managerdefault substitution variable name. For information on the availabledefault substitution variables, see the substitutions section ofTriggers file schema.

   • OVERRIDE_VARIABLE_VALUE with the value you want tooverride the default value for the default substitution variable with.

4. Commit the trigger configuration file to your default branch.

   After the triggers file is committed, Secure Source Manager triggers buildsbased on the configuration in your triggers file.

   Secure Source Manager reads the configuration files andassociated commit SHA or Git ref of the following types of events:

   • Forpush events, Secure Source Manager will read the commit SHA or Gitref when the push completes.
   • Forpull_request events, Secure Source Manager will read the commit SHAor Git ref when the pull request changes are pulled from.

View build status

When a build is triggered by a push or pull request event, the commit and buildstatus is displayed in the Secure Source Manager web interface.

The possible values for build status are as follows:

• SUCCESS: the build was completed successfully.
• WARNING: a problem occurred when trying to build.
• FAILURE: the build failed during execution.

You can prevent commits with unsuccessful builds from merging into importantbranches if you configure a branch protection rule to require a successfulstatus check from triggers configured in your triggers file. To learn moreabout branch protection, read theBranch protection overview.

To view the build status for a push event:

1. In the Secure Source Manager web interface, navigate to your repository.

   If the most recent push event triggered a build, the status is displayednext to the commit SHA. To view details on that status, click the status.

2. To view build status for previous commits, selectCommits to view thecommit history, and then click the status you want to view details for.

To view the build status for a pull request event:

1. In the Secure Source Manager web interface, clickPull requests.

2. Click the pull request you want to view.

   If builds were triggered by the pull request, you will see a section titledeitherAll checks were successful, orSome checks reported warnings.

What's next

• Use a triggers file toConnect to Cloud Build.