mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
77 lines
3.5 KiB
Plaintext
77 lines
3.5 KiB
Plaintext
// Module included in the following assemblies:
|
|
//
|
|
// * builds/triggering-builds-build-hooks.adoc
|
|
|
|
:_mod-docs-content-type: PROCEDURE
|
|
[id="builds-using-generic-webhooks_{context}"]
|
|
= Using generic webhooks
|
|
|
|
Generic webhooks are called from any system capable of making a web request. As with the other webhooks, you must specify a secret, which is 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`:
|
|
|
|
[source,yaml]
|
|
----
|
|
type: "Generic"
|
|
generic:
|
|
secretReference:
|
|
name: "mysecret"
|
|
allowEnv: true # <1>
|
|
----
|
|
<1> Set to `true` to allow a generic webhook to pass in environment variables.
|
|
|
|
.Procedure
|
|
|
|
. To set up the caller, supply the calling system with the URL of the generic
|
|
webhook endpoint for your build.
|
|
+
|
|
.Example generic webhook endpoint URL
|
|
[source]
|
|
----
|
|
https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
|
|
----
|
|
+
|
|
The caller must call the webhook as a `POST` operation.
|
|
|
|
. To call the webhook manually, enter the following `curl` command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ curl -X POST -k https://<openshift_api_host:port>/apis/build.openshift.io/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:
|
|
+
|
|
[source,yaml]
|
|
----
|
|
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 by 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 the following command:
|
|
+
|
|
[source,terminal]
|
|
----
|
|
$ curl -H "Content-Type: application/yaml" --data-binary @payload_file.yaml -X POST -k https://<openshift_api_host:port>/apis/build.openshift.io/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.
|
|
|
|
[NOTE]
|
|
====
|
|
{product-title} permits builds to be triggered by 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, {product-title} returns a warning in JSON format as part of its `HTTP 200 OK` response.
|
|
====
|