Manually build code in source repositories

This page explains how to create manual triggers to build code in source repositories. 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 specific time.

To learn how to start builds manually using the gcloud CLI or the Cloud Build API, see Starting builds manually.

Before you begin

  • Enable the Cloud Build API.

    Enable the 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 execute 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 execute a build.
  • Overriding defined substitution variable values at invocation time prior to invoking a build.

If you want to execute builds from your local working directory 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

Console

To create a manual trigger:

  1. Open the Triggers page:

    Open the Triggers page

  2. Select your project from the top of the page and click Open.

  3. Click Create trigger.

  4. Enter the following trigger settings:

    • Name: A name for your trigger.

    • Region: Select the region for your trigger.

      • If you select global as the region, Cloud Build uses the default pool to run your build.
      • If you select a non-global region and the build config file associated with the trigger specifies a private pool, Cloud Build uses the private pool 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 the build config file associated with the trigger does not specify a private pool, Cloud Build uses the default pool to run your build in the same region as your trigger.

    • Description (Optional): A description for your trigger.

    • Event: Select Manual invocation 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. You can specify 1st generation or 2nd generation as your source.

    • 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 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, you will 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.
        • 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.

  5. Click Create to create your manual trigger.

gcloud

To create a manual trigger:

  1. Open a terminal window.

  2. Run the following gcloud command to create a build trigger in your project:

    gcloud builds triggers create manual \
  --region=REGION \
  --name=TRIGGER_NAME \
  --repo=REPO_NAME \
  --repo-type=REPO_TYPE \
  --branch-pattern=BRANCH_PATTERN \
  --build-config=BUILD_CONFIG_FILE \
  --service-account=SERVICE_ACCOUNT

Where:

  • REGION is the region for your trigger.
  • TRIGGER_NAME is the name of your trigger.
  • REPO_NAME is the name of your repository.

  • REPO_TYPE is the type of repository you want to invoke a build on.

  • BRANCH_PATTERN is the branch name in your repository to invoke the build on. You can also specify a tag pattern instead using tag-pattern.

  • BUILD_CONFIG_FILE is the path to your build configuration file. You can also specify an inline build configuration file using --inline-config or a Dockerfile using --dockerfile, --dockerfile-dir, and dockerfile-image.

  • SERVICE_ACCOUNT is the email associated with your service account. If you don't include this flag, a default service account is used.

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

Running manual triggers

Console

To run a manual trigger using Google Cloud console:

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

    Open the triggers page

  2. Locate your trigger in the list.

  3. 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 execute your build.

    To run manual triggers on schedule, see Scheduling builds.

gcloud

To run a manual trigger using the gcloud command-line tool, run the following command:

      gcloud builds triggers run TRIGGER_NAME \
         --region=REGION \
         --branch=BRANCH_NAME \
         --substitutions=SUBSTITUTION_VAR=SUBSTITUTION_VALUE

Where:

  • TRIGGER_NAME is the name of your trigger.
  • REGION is the region for your trigger.
  • BRANCH_NAME is the name of your branch. You can also specify a tag using --tag or a commit ID using --sha.
  • [Optional]SUBSTITUTION_VAR is the variable name for your substitution value.
  • [Optional] SUBSTITUTION_VALUE is the value associated with your substitution variable.

To run manual triggers on schedule, see Scheduling builds.

Next steps