Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 6. Build triggers

To automate container image builds from Dockerfiles in {product-title}, you can configure builders on bare metal and virtual machines. Configure build triggers to start builds automatically when code changes occur, or start builds manually when needed.

6.1. Creating a build trigger
Copy link

To automate container image builds from your Git repositories, you can create a custom Git build trigger in {product-title}. Build triggers automatically build and push images when you push code to your Git repository.

The following steps can be replicated to create a build trigger using Github, Gitlab, or Bitbucket, however, you must configure the credentials for these services in your config.yaml file.

Note
  • If you want to use Github to create a build trigger, you must configure Github to be used with Red Hat Quay by creating an OAuth application. For more information, see "Creating an OAuth application Github".

Prerequisites

  • For Red Hat Quay on OpenShift Container Platform deployments, you have configured your OpenShift Container Platform environment for either bare metal builds or virtual builds.

Procedure

  1. Log in to your Red Hat Quay registry.
  2. In the navigation pane, click Repositories.
  3. Click Create Repository.
  4. Click the Builds tab.
  5. On the Builds page, click Create Build Trigger.
  6. Select the desired platform, for example, Github, Bitbucket, Gitlab, or use a custom Git repository. For this example, click Custom Git Repository Push.
  7. Enter a custom Git repository name, for example, git@github.com:<username>/<repo>.git. Then, click Next.

  8. When prompted, configure the tagging options by selecting one of, or both of, the following options:

    • Tag manifest with the branch or tag name. When selecting this option, the built manifest the name of the branch or tag for the git commit are tagged.

    • Add latest tag if on default branch. When selecting this option, the built manifest with latest if the build occurred on the default branch for the repository are tagged.

      Optionally, you can add a custom tagging template. There are multiple tag templates that you can enter here, including using short SHA IDs, timestamps, author names, committer, and branch names from the commit as tags. For more information, see "Tag naming for build triggers".

      After you have configured tagging, click Next.

  9. When prompted, select the location of the Dockerfile to be built when the trigger is invoked. If the Dockerfile is located at the root of the git repository and named Dockerfile, enter /Dockerfile as the Dockerfile path. Then, click Next.
  10. When prompted, select the context for the Docker build. If the Dockerfile is located at the root of the Git repository, enter / as the build context directory. Then, click Next.
  11. Optional. Choose an optional robot account. This allows you to pull a private base image during the build process. If you know that a private base image is not used, you can skip this step.
  12. Click Next. Check for any verification warnings. If necessary, fix the issues before clicking Finish.

  13. You are alerted that the trigger has been successfully activated. Note that using this trigger requires the following actions:

    • You must give the following public key read access to the git repository.

    • You must set your repository to POST to the following URL to trigger a build.

      Save the SSH Public Key, then click Return to <organization_name>/<repository_name>. You are redirected to the Builds page of your repository.

  14. On the Builds page, you now have a build trigger. For example:

    Example Build trigger

    After you have created a custom Git trigger, additional steps are required. Continue on to "Setting up a custom Git trigger".

    If you are setting up a build trigger for Github, Gitlab, or Bitbucket, continue on to "Manually triggering a build".

6.1.1. Setting up a custom Git trigger
Copy link

To complete the setup of your custom Git build trigger in {product-title}, you must provide read access to the SSH public key and configure a webhook endpoint. These steps enable your Git repository to automatically trigger builds when you push code.

These steps are only required if you are using a custom Git trigger.

6.1.1.1. Obtaining build trigger credentials
Copy link

To configure your custom Git trigger, you can obtain the SSH public key and webhook endpoint URL from the {product-title} user interface. These credentials are available on the Builds page of your repository.

Prerequisites

  • You have created a custom Git trigger.

Procedure

  1. On the Builds page of your repository, click the menu kebab for your custom Git trigger.
  2. Click View Credentials.

  3. Save the SSH Public Key and Webhook Endpoint URL.

    The key and the URL are available by selecting View Credentials from the Settings, or gear icon.

6.1.1.2. SSH public key access
Copy link

SSH public key access in {product-title} enables builder instances to clone Git repositories for custom build triggers. Install the SSH public key that {product-title} generates in your Git server configuration, either by adding it to the authorized_keys file or using Deploy Keys.

Depending on the Git server configuration, there are multiple ways to install the SSH public key that Quay generates for a custom Git trigger.

For example, documentation for Getting Git on a Server describes a describes how to set up a Git server on a Linux-based machine with a focus on managing repositories and access control through SSH. In this procedure, a small server is set up to add the keys to the $HOME/.ssh/authorize_keys folder, which provides access for builders to clone the repository.

For any Git repository management software that is not officially supported, there is usually a location to input the key that is often labeled as Deploy Keys.

6.1.1.3. Webhook reference
Copy link

The webhook reference provides the JSON payload format required to trigger builds in {product-title}. You must POST a JSON payload with commit, ref, and default_branch fields to the webhook URL to automatically start a build.

Note

This request requires a Content-Type header containing application/json in order to be valid.

Example webhook

{
  "commit": "1c002dd",                                   // required
  "ref": "refs/heads/master",                            // required
  "default_branch": "master",                            // required
  "commit_info": {                                       // optional
    "url": "gitsoftware.com/repository/commits/1234567", // required
    "message": "initial commit",                         // required
    "date": "timestamp",                                 // required
    "author": {                                          // optional
      "username": "user",                                // required
      "avatar_url": "gravatar.com/user.png",             // required
      "url": "gitsoftware.com/users/user"                // required
    },
    "committer": {                                       // optional
      "username": "user",                                // required
      "avatar_url": "gravatar.com/user.png",             // required
      "url": "gitsoftware.com/users/user"                // required
    }
  }
}
Copy to Clipboard Toggle word wrap

This can typically be accomplished with a post-receive Git hook, however it does depend on your server setup.

6.1.2. Tag naming for build triggers
Copy link

Tag naming for build triggers in {product-title} lets you create custom tags using templates that include commit information such as SHA, branch name, author, and date. You can use these templates to automatically tag your built images with meaningful identifiers based on the Git commit that triggered the build.

One option is to include any string of characters assigned as a tag for each built image. Alternatively, you can use the following tag templates on the Configure Tagging section of the build trigger to tag images with information from each commit:

Configure Tagging

  • ${commit}: Full SHA of the issued commit
  • ${parsed_ref.branch}: Branch information (if available)
  • ${parsed_ref.tag}: Tag information (if available)
  • ${parsed_ref.remote}: The remote name
  • ${commit_info.date}: Date when the commit was issued
  • ${commit_info.author.username}: Username of the author of the commit
  • ${commit_info.short_sha}: First 7 characters of the commit SHA
  • ${committer.properties.username}: Username of the committer

This list is not complete, but does contain the most useful options for tagging purposes. You can find the complete tag template schema on this page.

For more information, see Set up custom tag templates in build triggers for Red Hat Quay and Quay.io.

6.1.3. Skipping a source control-triggered build
Copy link

You can skip source control-triggered builds in {product-title} by adding [skip build] or [build skip] to your commit message. This prevents the build system from automatically building images for commits that do not require new builds.

6.2. Manually triggering a build
Copy link

Manual build triggering in {product-title} lets you start builds on demand without waiting for automatic triggers from source control. You can manually trigger builds from the Builds page by selecting a build trigger and specifying a commit ID.

Procedure

  1. On the Builds page, Start new build.
  2. When prompted, select Invoke Build Trigger.
  3. Click Run Trigger Now to manually start the process.

  4. Enter a commit ID from which to initiate the build, for example, 1c002dd.

    After the build starts, you can see the build ID on the Repository Builds page.

  5. You can check the status of your build by clicking the commit in the Build History page, or by running the following command: 

    $ oc get pods -n virtual-builders
    Copy to Clipboard Toggle word wrap

    Example output

    NAME                                               READY   STATUS    RESTARTS   AGE
f192fe4a-c802-4275-bcce-d2031e635126-9l2b5-25lg2   1/1     Running   0          7s
    Copy to Clipboard Toggle word wrap

  6. After the build has completed, the oc get pods -n virtual-builders command returns no resources: 

    $ oc get pods -n virtual-builders
    Copy to Clipboard Toggle word wrap

    Example output

    No resources found in virtual-builders namespace.
    Copy to Clipboard Toggle word wrap

Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top