Red Hat OpenShift Developer II: Building and Deploying Cloud-native Applications

In Red Hat OpenShift you can define build triggers to start new builds based on specified events. You can use these build triggers to keep your application containers updated with any new container images or code changes that affect your application. These are the main available triggers in Red Hat OpenShift:

Image change triggers free developers from watching for changes in an application parent image. The oc new-app command creates image change triggers for applications that use either the Source or Docker build strategies:

To keep images in the image stream up-to-date with images from external registries, you must periodically run the oc import-image command.

To view the triggers associated with a build configuration use the oc describe bc command, as shown in the following example:

[user@host ~]$ oc describe bc/name
...output omitted...

Webhook GitHub:
	URL:	https://api.ocp4.example.com/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<app>/webhooks/<secret>/github
Webhook Generic:
	URL:		https://api.ocp4.example.com/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<app>/webhooks/<secret>/generic

...output omitted...

To add an image change trigger to a build configuration, use the oc set triggers command:

[user@host ~]$ oc set triggers bc/name --from-image=project/image:tag

A single build configuration cannot include multiple image change triggers.

To remove an image change trigger from a build configuration, use the oc set triggers command with the --remove option:

[user@host ~]$ oc set triggers bc/name --from-image=project/image:tag --remove

For applications deployed by using a container image, you can set triggers on the deployment of the application by using the following command:

[user@host ~]$ oc set trigger deployment/name

And you can find the current triggers for a deployment in the image.openshift.io/triggers: annotation:

[user@host ~]$ oc describe deployment/name
...output omitted...

Annotations:            deployment.kubernetes.io/revision: 3
                        image.openshift.io/triggers:
[{"from":{"kind":"ImageStreamTag","name":"hello:latest"},
"fieldPath":"spec.template.spec.containers[?(@.name==\"hello\")].image"}]


...output omitted...

Use the oc set triggers --help command to see the options used to add and remove a configuration change trigger.

Red Hat OpenShift webhook triggers are HTTP API endpoints that start new builds. Use a webhook to integrate Red Hat OpenShift with a Version Control System (VCS), such as Git. This integration means that the application's source code changes trigger a new build in Red Hat OpenShift that uses the latest code.

Red Hat OpenShift builds can only download source code from a Git server.

Red Hat OpenShift provides webhook types that support API endpoints compatible with the following VCS services:

Each VCS has a repository configuration section that enables you to provide a webhook. The VCS then sends a request to the webhook URL for each event that you specify in the configuration, such as new commits.

Red Hat OpenShift also provides a generic webhook type that takes a payload defined by Red Hat OpenShift. You can use the generic webhook to start a build without using a VCS, such as from a Jenkins or Tekton pipeline. See the product documentation references at the end of this section for the syntax of the generic webhook payload and the HTTP API requests for each type of webhook.

Webhooks use a secret with the WebHookSecretKey key that defines a unique value that you must provide when invoking the webhook. The webhook definition must then reference the secret. The secret ensures the uniqueness of the webhook URL, preventing others from triggering the build. When you or OpenShift create a trigger, OpenShift generates the secret by default.

The oc new-app command creates a generic and a Git webhook. To add other types of webhooks to a build configuration, you must use the oc set triggers command. For example, the following commands add a GitLab webhook to a build configuration:

[user@host ~]$ oc set triggers bc/name --from-gitlab

If the build configuration already includes a GitLab webhook, then the previous command resets the authentication secret embedded in the URL. You must update your GitLab projects to use the new webhook URL.

To remove an existing webhook from a build configuration, use the oc set triggers command with the --remove option. For example, the following command removes a GitLab webhook from a build configuration:

[user@host ~]$ oc set triggers bc/name --from-gitlab --remove

The oc set triggers bc command also supports the --from-github and --from-bitbucket options to create triggers specific to each VCS platform.

To retrieve a webhook URL, use the oc describe bc/name command and look for the specific type of webhook you need. To retrieve the secret to use in the webhook URL, use the oc get bc/name -o yaml command.