Manually build code in source repositories
This page explains how to create manual triggers to build codein source repositories. Manual triggers can be usedto invoke builds manually, with the ability to override defined substitution variable values atinvocation time prior to running a build. You can also schedule manualtriggers to automatically run at a specific time.
To learn how to start builds manually using the gcloud CLI orthe Cloud Build API, seeStarting builds manually.
Before you begin
Enable the Cloud Build API.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission.Learn how to grant roles.
- Have your source code ready.
Manual triggers
Manual triggers enable you to set up builds that are only executedwhen you invoke your trigger on connected repositories. Let's say you're creatinga pipeline for deploying your source code to a staging or production environment.You might want to automate your workflow, but are only looking to execute buildsmanually. 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 inmanually each time you execute a build.
- Overriding defined substitution variable values at invocation time prior toinvoking a build.
If you want to execute builds from your local working directory instead of a hosted repositoryor want to submit builds without creating a trigger, you can run the followinggcloud command in your working directory:
gcloud builds submit --configBUILD_CONFIGSOURCE_CODEWhere:
- 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 thegcloud command to start builds manuallyin your local directory, seeStarting builds manually.
Creating manual triggers
Console
To create a manual trigger:
Open theTriggers page:
Select your project from the top of the page and clickOpen.
ClickCreate trigger.
Enter the following trigger settings:
- Name: A name for your trigger.
Region: Select theregion for your trigger.
- If you selectglobal as the region,Cloud Build uses the defaultpool to run your build.
- If you select a non-global region and thebuild config file associated with the triggerspecifies aprivate pool, Cloud Build uses the privatepool to run your build. In this case, the region you specify in your trigger must match the region where you created your private pool.
- If you select a non-global region and thebuild config file associated with the triggerdoesnot specify a private pool,Cloud Build uses the defaultpool to run your build in the same regionas your trigger.
Description (Optional): A description for your trigger.
Event: SelectManual invocation to set up your trigger so that buildsonly run when the trigger is manually invoked.
Source: Select the repository to build when the manual trigger runs. You can specify1st generation or2nd generation as your source.
Note: The region of your repository must matchthe region of your trigger. If your source is inCloud Source Repositories, your repository isnot connected to a particular region, but toyour project.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.
Revision: Select the branch or tag to build when the manual triggerruns.
Branch: Set a trigger to build on this branch.You must specify a literal value. Regular expressions are not currentlysupported.
Tag: Set a trigger to build on this tag. You must specify a literalvalue. Regular expressions are not currently supported.
Configuration: Select the build config file located inyour remote repository or create an inline build config file touse 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
Dockerfilefor your configuration.
Location: Specify the location for your configuration.
- Repository: If your config file is located in yourremote repository, provide the location of yourbuild config file, the
Dockerfiledirectory, or the buildpacks directory. If your build configtype is aDockerfileor a buildpack, you will need to providea name for the resulting image and optionally, a timeout for yourbuild. When you've provided theDockerfileor buildpackimage name, you'll see a preview of thedocker buildorpackcommand that your build will execute. - Inline: If you selectedCloud Build configuration file (yaml or json) as your configuration option, you can specify your build config inline. ClickOpen Editor to write your build config file in the Google Cloud console using YAML or JSON syntax. ClickDone to save your build config.
Dockerfile.- Repository: If your config file is located in yourremote repository, provide the location of yourbuild config file, the
- Type: Select the type of configuration to use for your build.
ClickCreate to create your manual trigger.
gcloud
For a complete list of flags, see thegcloud reference for how to create manual triggers.
Running manual triggers
Console
To run a manual trigger using Google Cloud console:
Open theTriggers page in the Google Cloud console.
Locate your trigger in the list.
ClickRun trigger.
After clickingRun trigger, you will see theRun trigger window paneon the right side. If you specified fields such as a branch name, tagname, or substitution variables, you will be able to override these fieldsat invocation time.
Note: You cannot specify any new fields or variables in this window pane. To do so, seeinstructions in thegcloudtab in this section.If you specified new variable values for your substitution, clickRun triggerto execute your build.
To run manual triggers on schedule, seeScheduling builds.
gcloud
To run a manual trigger using thegcloud command-line tool, run the followingcommand:
gcloudbuildstriggersrunTRIGGER_NAME\--region=REGION\--branch=BRANCH_NAME\--substitutions=SUBSTITUTION_VAR=SUBSTITUTION_VALUEWhere:
TRIGGER_NAMEis the name of your trigger.REGIONis theregion for your trigger.BRANCH_NAMEis the name of your branch. You canalso specify a tag using--tagor a commit ID using--sha.- [Optional]
SUBSTITUTION_VARis the variable name for your substitution value. - [Optional]
SUBSTITUTION_VALUEis the value associated with your substitution variable.
To run manual triggers on schedule, seeScheduling builds.
Next steps
- Learn how tostart builds manually using
gcloudcommands or the Cloud Build API. - Learn how toschedule builds.
- Learn how tocreate and manage triggers.
- Learn how toview build results.
- Learn how totroubleshoot build errors.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.