Chapter 8. Triggering and modifying builds

Procedure

1. To configure a GitHub Webhook:

   1. After creating a BuildConfig from a GitHub repository, run:

      $ oc describe bc/<name-of-your-BuildConfig>

      This generates a webhook GitHub URL that looks like:

      <https://api.starter-us-east-1.openshift.com:443/oapi/v1/namespaces/nsname/buildconfigs/bcname/webhooks/<secret>/github>.

   2. Cut and paste this URL into GitHub, from the GitHub web console.
   3. In your GitHub repository, select Add Webhook from Settings Webhooks.
   4. Paste the URL output (similar to above) into the Payload URL field.
   5. Change the Content Type from GitHub’s default application/x-www-form-urlencoded to application/json.

   6. Click Add webhook.

      You should see a message from GitHub stating that your webhook was successfully configured.

      Now, whenever you push a change to your GitHub repository, a new build will automatically start, and upon a successful build a new deployment will start.

      Note

      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 BuildConfig and trigger it by your Gogs server as well.

2. Given a file containing a valid JSON payload, such as payload.json, you can manually trigger the webhook with 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.

Procedure

1. To configure a GitLab Webhook:

   1. Describe the BuildConfig to get the webhook URL:

      $ oc describe bc <name>

   2. Copy the webhook URL, replacing <secret> with your secret value.
   3. Follow the GitLab setup instructions to paste the webhook URL into your GitLab repository settings.

2. Given a file containing a valid JSON payload, such as payload.json, you can manually trigger the webhook with 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.

Procedure

1. To configure a Bitbucket Webhook:

   1. Describe the 'BuildConfig' to get the webhook URL:

      $ oc describe bc <name>

   2. Copy the webhook URL, replacing <secret> with your secret value.
   3. Follow the Bitbucket setup instructions to paste the webhook URL into your Bitbucket repository settings.

2. Given a file containing a valid JSON payload, such as payload.json, you can manually trigger the webhook with 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.

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.