Chapter 8. Triggering and modifying builds

Procedure

1. Back up the webhook configuration. Choose either

   ValidatingWebhookConfiguration

   or

   MutatingWebhookConfiguration

   for the

   <webhook_configuration>

   value.

   oc get <webhook_configuration> <webhook_name> -o yaml > webhook-backup.yaml

2. Delete the webhook.

   oc delete <webhook_configuration> <webhook_name>

3. Fix the webhook configuration to exclude infrastructure namespaces when you reapply it.

   Example

   apiVersion: admissionregistration.k8s.io/v1
   kind: MutatingWebhookConfiguration
   metadata:
     name: machine-api
   webhooks:
     - name: default.machine.machine.openshift.io
       rules:
         - apiGroups: [""]
           apiVersions: ["v1"]
           operations: ["CREATE", "UPDATE"]
           resources: ["pods"]
           scope: "*"
       clientConfig:
         service:
           namespace: machine-api-operator-webhook
           name: openshift-machine-api
           path: "/validate"
       admissionReviewVersions: ["v1"]
       sideEffects: None
       timeoutSeconds: 5
       namespaceSelector:
         matchExpressions:
           - key: kubernetes.io/metadata.name
             operator: NotIn
             values:
               - openshift
               - openshift-apiserver
               - openshift-authentication
               - openshift-monitoring
               - kube-system
               - kube-public
               - kube-node-lease
               - default

   Where

   kind

   is the type of webhook configuration you are using. Valid values are

   ValidatingWebhookConfiguration

   or

   MutatingWebhookConfiguration

   .

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:

      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

   curl

   :

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

   https://<openshift_api_host:port>/apis/build.openshift.io/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>/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:

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