Skip to content

Latest commit

 

History

History
92 lines (84 loc) · 3.23 KB

builds-using-generic-webhooks.adoc

File metadata and controls

92 lines (84 loc) · 3.23 KB

Using generic webhooks

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.

Procedure

  1. 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.

  2. 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 by webhook are ignored. Set the allowEnv field to true on the webhook definition to enable this behavior.

  3. 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.

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.