type: "GitHub"
github:
secretReference:
name: "mysecret"
When defining a BuildConfig, you can define triggers to control the
circumstances in which the BuildConfig should be run. The following build
triggers are available:
Webhook triggers allow you to trigger a new build by sending a request to the OpenShift Container Platform API endpoint. You can define these triggers using GitHub, GitLab, Bitbucket, or Generic webhooks.
Currently, OpenShift Container Platform webhooks support only the analogous versions of the push event for each of the Git-based source code management systems (SCMs). All other event types are ignored.
When the push events are processed, the OpenShift Container Platform master host confirms if
the branch reference inside the event matches the branch reference in the
corresponding BuildConfig. If so, it then checks out the exact commit
reference noted in the webhook event on the OpenShift Container Platform build. If they do
not match, no build is triggered.
|
|
For all webhooks, you must define a Secret with a key named WebHookSecretKey and the
value being the value to be supplied when invoking the webhook. The webhook definition
must then reference the secret. The secret ensures the uniqueness of the URL, preventing
others from triggering the build. The value of the key will be compared to the secret provided
during the webhook invocation.
For example here is a GitHub webhook with a reference
to a secret named mysecret:
type: "GitHub"
github:
secretReference:
name: "mysecret"The secret is then defined as follows. Note that the value of the secret is base64 encoded as
is required for any data field of a Secret object.
- kind: Secret
apiVersion: v1
metadata:
name: mysecret
creationTimestamp:
data:
WebHookSecretKey: c2VjcmV0dmFsdWUxGitHub webhooks handle the call
made by GitHub when a repository is updated. When defining the trigger, you must
specify a secret, which will be part of the URL you supply to GitHub when
configuring the webhook.
Example GitHub webhook definition:
type: "GitHub"
github:
secretReference:
name: "mysecret"|
The secret used in the webhook trigger configuration is not the same as |
The payload URL is returned as the GitHub Webhook URL by the oc describe command
(see Displaying Webhook URLs), and is structured as follows:
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
To configure a GitHub Webhook:
Describe the build configuration to get the webhook URL:
$ oc describe bc <name>
Copy the webhook URL, replacing <secret> with your secret value.
Follow the GitHub setup instructions to paste the webhook URL into your GitHub repository settings.
|
Gogs supports the same webhook payload format as GitHub.
Therefore, if you are using a Gogs server, you can define a GitHub webhook
trigger on your |
Given a file containing a valid JSON payload, such as payload.json, you can manually trigger the
webhook via curl:
$ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
The -k argument is only necessary if your API server does not have a properly
signed certificate.
GitLab webhooks
handle the call made by GitLab when a repository is updated. As with the GitHub
triggers, you must specify a secret. The following example is
a trigger definition YAML within the BuildConfig:
type: "GitLab"
gitlab:
secretReference:
name: "mysecret"The payload URL is returned as the GitLab Webhook URL by the oc describe command
(see Displaying Webhook URLs), and is structured as follows:
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab
To configure a GitLab Webhook:
Describe the build configuration to get the webhook URL:
$ oc describe bc <name>
Copy the webhook URL, replacing <secret> with your secret value.
Follow the GitLab setup instructions to paste the webhook URL into your GitLab repository settings.
Given a file containing a valid JSON payload, such as payload.json, you can manually trigger the
webhook via curl:
$ curl -H "X-GitLab-Event: Push Hook" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab
The -k argument is only necessary if your API server does not have a properly
signed certificate.
Bitbucket webhooks
handle the call made by Bitbucket when a repository is updated. Similar to the
previous triggers, you must specify a secret. The following example is a
trigger definition YAML within the BuildConfig:
type: "Bitbucket"
bitbucket:
secretReference:
name: "mysecret"The payload URL is returned as the Bitbucket Webhook URL by the oc describe command
(see Displaying Webhook URLs), and is structured as follows:
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket
To configure a Bitbucket Webhook:
Describe the build configuration to get the webhook URL:
$ oc describe bc <name>
Copy the webhook URL, replacing <secret> with your secret value.
Follow the Bitbucket setup instructions to paste the webhook URL into your Bitbucket repository settings.
Given a file containing a valid JSON payload, such as payload.json, you can manually trigger the
webhook via curl:
$ curl -H "X-Event-Key: repo:push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket
The -k argument is only necessary if your API server does not have a properly
signed certificate.
Generic webhooks are invoked from any system capable of making a web request.
As with the other webhooks, you must specify a secret, which will be part of
the URL that the caller must use to trigger the build. The secret ensures the
uniqueness of the URL, preventing others from triggering the build. The
following is an example trigger definition YAML within the BuildConfig:
type: "Generic"
generic:
secretReference:
name: "mysecret"
allowEnv: true (1)| 1 | Set to true to allow a generic webhook to pass in environment variables. |
To set up the caller, supply the calling system with the URL of the generic webhook endpoint for your build:
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
The caller must invoke the webhook as a POST operation.
To invoke the webhook manually you can use curl:
$ curl -X POST -k https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
The HTTP verb must be set to POST. The insecure -k flag is specified to
ignore certificate validation. This second flag is not necessary if your cluster
has properly signed certificates.
The endpoint can accept an optional payload with the following format:
git:
uri: "<url to git repository>"
ref: "<optional git reference>"
commit: "<commit hash identifying a specific git commit>"
author:
name: "<author name>"
email: "<author e-mail>"
committer:
name: "<committer name>"
email: "<committer e-mail>"
message: "<commit message>"
env: (1)
- name: "<variable name>"
value: "<variable value>"| 1 | Similar to the BuildConfig
environment variables, the environment variables defined here are made
available to your build. If these variables collide with the BuildConfig
environment variables, these variables take precedence. By default, environment
variables passed via webhook are ignored. Set the allowEnv field to true on
the webhook definition to enable this behavior. |
To pass this payload using curl, define it in a file named
payload_file.yaml and run:
$ curl -H "Content-Type: application/yaml" --data-binary @payload_file.yaml -X POST -k https://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
The arguments are the same as the previous example with the addition of a header
and a payload. The -H argument sets the Content-Type header to
application/yaml or application/json depending on your payload format.
The --data-binary argument is used to send a binary payload with newlines
intact with the POST request.
|
OpenShift Container Platform permits builds to be triggered via the generic webhook even if
an invalid request payload is presented (for example, invalid content type,
unparsable or invalid content, and so on). This behavior is maintained for
backwards compatibility. If an invalid request payload is presented,
OpenShift Container Platform returns a warning in JSON format as part of its |
Use the following command to display any webhook URLs associated with a build configuration:
$ oc describe bc <name>
If the above command does not display any webhook URLs, then no webhook trigger is defined for that build configuration. See Setting Triggers to manually add triggers.
Image change triggers allow your build to be automatically invoked when a new version of an upstream image is available. For example, if a build is based on top of a RHEL image, then you can trigger that build to run any time the RHEL image changes. As a result, the application image is always running on the latest RHEL base image.
Configuring an image change trigger requires the following actions:
Define an ImageStream that points to the upstream image you want to
trigger on:
kind: "ImageStream"
apiVersion: "v1"
metadata:
name: "ruby-20-centos7"This defines the image stream that is tied to a container image repository
located at <system-registry>/<namespace>/ruby-20-centos7. The
<system-registry> is defined as a service with the name docker-registry
running in OpenShift Container Platform.
If an image stream is the base image for the build, set the from field in the build strategy to point to the image stream:
strategy:
sourceStrategy:
from:
kind: "ImageStreamTag"
name: "ruby-20-centos7:latest"In this case, the sourceStrategy definition is consuming the latest tag of
the image stream named ruby-20-centos7 located within this namespace.
Define a build with one or more triggers that point to image streams:
type: "imageChange" (1)
imageChange: {}
type: "imagechange" (2)
imageChange:
from:
kind: "ImageStreamTag"
name: "custom-image:latest"| 1 | An image change trigger that monitors the ImageStream and Tag as
defined by the build strategy’s from field. The imageChange object here
must be empty. |
| 2 | An image change trigger that monitors an arbitrary image stream. The
imageChange part in this case must include a from field that references
the ImageStreamTag to monitor. |
When using an image change trigger for the strategy image stream, the generated build is supplied with an immutable Docker tag that points to the latest image corresponding to that tag. This new image reference will be used by the strategy when it executes for the build.
For other image change triggers that do not reference the strategy image stream, a new build will be started, but the build strategy will not be updated with a unique image reference.
In the example above that has an image change trigger for the strategy, the resulting build will be:
strategy:
sourceStrategy:
from:
kind: "DockerImage"
name: "172.30.17.3:5001/mynamespace/ruby-20-centos7:<immutableid>"This ensures that the triggered build uses the new image that was just pushed to the repository, and the build can be re-run any time with the same inputs.
In addition to setting the image field for all Strategy types, for custom
builds, the OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE environment variable is checked.
If it does not exist, then it is created with the immutable image reference. If
it does exist then it is updated with the immutable image reference.
If a build is triggered due to a webhook trigger or manual request,
the build that is created uses the <immutableid> resolved from the
ImageStream referenced by the Strategy. This ensures that builds
are performed using consistent image tags for ease of reproduction.
|
Image streams that point to container images in v1 Docker registries only trigger a build once when the image stream tag becomes available and not on subsequent image updates. This is due to the lack of uniquely identifiable images in v1 Docker registries. |
A configuration change trigger allows a build to be automatically invoked as
soon as a new BuildConfig is created. The following is an example trigger
definition YAML within the BuildConfig:
type: "ConfigChange"|
Configuration change triggers currently only work when creating a new
|
Triggers can be added to and removed from build configurations with oc set
triggers. For example, to set a GitHub webhook trigger on a build
configuration, use:
$ oc set triggers bc <name> --from-github
To set an imagechange trigger, use
$ oc set triggers bc <name> --from-image='<image>'
To remove a trigger, add --remove:
$ oc set triggers bc <name> --from-bitbucket --remove
|
When a webhook trigger already exists, adding it again regenerates the webhook secret. |
For more information, consult the help documentation with oc set triggers
--help