Chapter 8. Triggering and modifying builds

Procedure

1. Configure a GitHub Webhook.

   1. After creating a BuildConfig object from a GitHub repository, run the following command:

      $ oc describe bc/<name_of_your_BuildConfig>

      This command generates a webhook GitHub URL.

      Example output

      https://api.starter-us-east-1.openshift.com:443/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/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 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, when you push a change to your GitHub repository, a new build automatically starts, and upon a successful build a new deployment starts.

      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 the following curl command:

   $ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/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. Configure a GitLab Webhook.

   1. Get the webhook URL by entering the following command:

      $ 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 the following curl command:

   $ curl -H "X-GitLab-Event: Push Hook" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/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. Configure a Bitbucket Webhook.

   1. Get the webhook URL by entering the following command:

      $ 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 by entering the following curl command:

   $ curl -H "X-Event-Key: repo:push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/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.

   Example generic webhook endpoint URL

   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.

2. To call the webhook manually, enter the following curl command:

   $ 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:

   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 the following command:

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