This page explains how to create manual triggers. Manual triggers can be used to invoke builds manually, with the ability to override defined substitution variable values at invocation time prior to running a build. You can also schedule manual triggers to automatically run at a specifc time.
To learn how to start builds manually using the gcloud
command line tool or
the Cloud Build API, see
Starting builds manually.
Before you begin
- Enable the Cloud Build API.
- Have your source code ready.
Manual triggers
Manual triggers enable you to set up builds that are only executed when you invoke your trigger on connected repositories. Let's say you're creating a pipeline for deploying your source code to a staging or production environment. You might want to automate your workflow, but are only looking to invoke builds manually. You can define manual triggers to do so.
Manual triggers enable you to manually invoke builds by:
- Fetching source code from a hosted repository with a specified branch or tag.
- Parametizing your build with substitutions that don't need to be passed in manually each time you invoke a build.
- Overriding defined substitution variable values at invocation time prior to invoking a build.
To invoke builds from your local working direrctory instead of a hosted repository
or want to submit builds without creating a trigger, you can run the following
gcloud
command in your working directory:
gcloud builds submit --config build-config source-code
Where:
- build-config is the path to the build config file.
- source-code is the path or URL source code.
To learn more about how to use the gcloud
command to start builds manually
in your local directory, see Starting builds manually.
Creating manual triggers
To create a manual trigger:
Open the Triggers page:
Select your project from the top of the page and click Open.
Click Create trigger.
Enter the following trigger settings:
- Name: A name for your trigger.
- Description (Optional): A description for your trigger.
- When: Select Manually run to set up your trigger so that builds only run when the trigger is manually invoked.
- Source: Select the repository to build when the manual trigger runs.
- Revision: Select the branch or tag to build when the manual trigger
runs.
- Branch: Set a trigger to build on this branch. You must specify a literal value. Regular expressions are not currently supported.
- Tag: Set a trigger to build on this tag. You must specify a literal value. Regular expressions are not currently supported.
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.
Location: Specify the location for your configuration.
- Repository: If your config file is in located in your
remote repository, provide the location of your
build config file or the
Dockerfile
directory and a name for the resulting image. If your configuration is aDockerfile
, you can optionally provide a timeout for your build. When you've provided theDockerfile
and image name, you'll see a preview of thedocker build
command that your build will execute. - 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.
- Repository: If your config file is in located in your
remote repository, provide the location of your
build config file or the
- Type: Select the type of configuration to use for your build.
Click Create to create your manual trigger.
Scheduling your build
You can schedule builds to run at a specified time using manual triggers in
the Google Cloud Console. Currently, you cannot schedule builds using
gcloud
commands or by making API calls. If you have not created a manual trigger, see Creating manual triggers.
Open the Triggers page:
Click on the name of the manual trigger you want to schedule builds for.
You will see the Edit trigger page.
Click Run on schedule to schedule your build.
You will see the Run trigger on schedule panel on the right side.
Enable the Cloud Scheduler API.
You will only be prompted to enable the Cloud Scheduler API the first time you schedule a build.
Select a service account that will be used by Cloud Scheduler to invoke your trigger.
You will see the default scheduling service account in the following format, where project-id is the project ID for your project:
cloud-build-trigger-scheduler@project-id.iam.gserviceaccount.com
When selected, the default service account will automatically be created for you. The Cloud Build Editor role will be granted to the service account upon creation. We recommend not deleting the default service account used by Cloud Scheduler to invoke your trigger. If the service account is deleted or if permissions associated with the service account are edited, you can navigate to the IAM page to manually add the service account and grant it the Cloud Build Editor role. You may need to wait up to an hour for any existing Cloud Scheduler jobs to resume after recreating the service account.
Click Continue.
Enter the following Cloud Scheduler job settings:
- Name: A name for your Cloud Scheduler job.
- Description (Optional): A description for your Cloud Scheduler job.
- Frequency: Select how frequently you would like your trigger to
run. You can choose a frequency from the drop-down menu or enter a
custom value using cron syntax. If you want your manual trigger to
run everyday at 6 AM, you can specify your frequency in cron syntax as
0 6 * * *
. To learn more about cron syntax, see Configuring cron job schedules. - Time Zone: Select your time zone.
Click Create to create your Cloud Scheduler job.
If you would like to view your Cloud Scheduler job, click View. Otherwise, click Done to close the panel.
If you update the revision associated with your manual trigger, you will need to manually update the Cloud Scheduler job associated with your trigger. For example, if you update the branch name for your manual trigger, you will need to manually update the name of the branch in your job. You can make the updates on the Body of the Cloud Scheduler job by editing your selected job on the Cloud Scheduler page. To identify the Cloud Scheduler associated with your trigger, enter your trigger ID into the filter bar at the top of the page.
If you delete a scheduler job associated with your trigger, your trigger will no longer run at the specified time indicated in the job. If you delete a trigger, it will not automatically delete all jobs associated with your trigger. If you disable a trigger, your job will still exist and builds will continue to be invoked.
To learn how to delete a job, see Deleting a job. To learn how to delete or disable a trigger, see Deleting a build trigger or Disabling a build trigger.
Running manual triggers
To run a manual trigger using Google Cloud Console:
Open the Triggers page in the Google Cloud Console.
Locate your trigger in the list.
Click Run trigger.
After clicking Run trigger, you will see the Run trigger window pane on the right side. If you specified fields such as a branch name, tag name, or substitution variables, you will be able to override these fields at invocation time.
If you specified new variable values for your substitution, click Run trigger to invoke your build.
Next steps
- Learn how to start builds manually using
gcloud
commands or the Cloud Build API. - Learn how to create and manage triggers.
- Learn how to view build results.