Home
Products
Red Hat OpenShift Pipelines
1.24
Creating CI/CD pipelines
Chapter 6. Using ClusterTriggerBindings with OpenShift Pipelines

Chapter 6. Using ClusterTriggerBindings with OpenShift Pipelines

You can trigger pipeline runs automatically in response to Git repository events by using the ClusterTriggerBinding resources that OpenShift Pipelines installs. These cluster-scoped bindings extract parameters from webhook payloads for GitHub, GitLab, and Bitbucket.

6.1. ClusterTriggerBindings overview
Copy link

You can use ClusterTriggerBinding resources in OpenShift Pipelines to extract fields from webhook event payloads and pass them as parameters to your TriggerTemplate resources.

Unlike a TriggerBinding resource, which is scoped to a single namespace, a ClusterTriggerBinding resource is cluster-scoped and reusable in all namespaces. OpenShift Pipelines installs a set of ClusterTriggerBinding resources for common Git hosting provider events. You can reference these preinstalled bindings in your Trigger or EventListener resources without writing custom parameter extraction logic.

The following example shows the structure of a ClusterTriggerBinding resource that extracts fields from a GitHub push event:

apiVersion: triggers.tekton.dev/v1beta1
kind: ClusterTriggerBinding
metadata:
  name: github-push
spec:
  params:
  - name: git-revision
    value: $(body.head_commit.id)
  - name: git-repo-url
    value: $(body.repository.url)
  - name: git-repo-name
    value: $(body.repository.name)

To reference a ClusterTriggerBinding resource in a Trigger resource, set the kind field to ClusterTriggerBinding in the bindings list:

apiVersion: triggers.tekton.dev/v1
kind: Trigger
metadata:
  name: my-trigger
spec:
  bindings:
  - ref: github-push
    kind: ClusterTriggerBinding
  template:
    ref: my-trigger-template

Without the kind: ClusterTriggerBinding field, Tekton Triggers looks for a namespace-scoped TriggerBinding resource with that name instead.

You can list the ClusterTriggerBinding resources installed in your cluster by running the following command:

$ oc get clustertriggerbindings

6.2. Triggering a pipeline run from a GitHub push event
Copy link

Trigger a pipeline run automatically when code is pushed to a GitHub repository by using the preinstalled github-push ClusterTriggerBinding resource in OpenShift Pipelines.

Prerequisites

You have access to an OpenShift Container Platform cluster with Red Hat OpenShift Pipelines installed.
You have installed the OpenShift Pipelines CLI (tkn).
You have cluster-admin or equivalent permissions, or you have permission to create EventListener, TriggerTemplate, Route, and Secret resources in your namespace.
You have a GitHub repository to which you have admin access, so that you can configure webhooks.
You have a pipeline that accepts git-url and git-revision parameters, or you can adapt the TriggerTemplate in this procedure to match your pipeline.

Procedure

Verify that the github-push ClusterTriggerBinding resource is installed:
```
$ oc get clustertriggerbinding github-push -o yaml
```
The output shows the binding and its parameter definitions extracted from the GitHub push event payload.
Create a webhook secret to validate incoming GitHub events. Replace <your_secret_token> with a secure, random string that you will also enter when configuring the GitHub webhook:
```
apiVersion: v1
kind: Secret
metadata:
  name: github-webhook-secret
type: Opaque
stringData:
  secretToken: "<your_secret_token>"
```
Apply the manifest by running the following command:
```
$ oc apply -f github-webhook-secret.yaml
```

Create a TriggerTemplate resource that defines how to create a PipelineRun from the parameters supplied by the github-push ClusterTriggerBinding. Replace <your_pipeline_name> with the name of your pipeline:

apiVersion: triggers.tekton.dev/v1
kind: TriggerTemplate
metadata:
  name: github-push-pipeline
spec:
  params:
  - name: git-revision
    description: The SHA of the commit that triggered the push
  - name: git-repo-clone-url
    description: The HTTPS clone URL of the repository
  - name: git-repo-name
    description: The name of the repository
  resourcetemplates:
  - apiVersion: tekton.dev/v1
    kind: PipelineRun
    metadata:
      generateName: github-push-run-
    spec:
      serviceAccountName: pipeline
      pipelineRef:
        name: <your_pipeline_name>
      params:
      - name: git-url
        value: $(tt.params.git-repo-clone-url)
      - name: git-revision
        value: $(tt.params.git-revision)
      - name: deployment-name
        value: $(tt.params.git-repo-name)
      workspaces:
      - name: shared-workspace
        volumeClaimTemplate:
          spec:
            accessModes:
            - ReadWriteOnce
            resources:
              requests:
                storage: 500Mi

Important

Use the git-repo-clone-url parameter, not git-repo-url, when you need the repository URL for cloning. The git-repo-url parameter maps to $(body.repository.url), which is the GitHub REST API URL and cannot be used for cloning. The git-repo-clone-url parameter maps to $(body.repository.html_url), which is the correct HTTPS URL for cloning the repository with git-clone or similar tasks.

Apply the manifest by running the following command:

$ oc apply -f github-push-pipeline-template.yaml

Create an EventListener resource that exposes an HTTP endpoint, references the github-push ClusterTriggerBinding, and uses the GitHub interceptor to validate the webhook signature and filter for push events only:

apiVersion: triggers.tekton.dev/v1
kind: EventListener
metadata:
  name: github-push-listener
spec:
  serviceAccountName: pipeline
  triggers:
  - interceptors:
    - ref:
        name: github
      params:
      - name: secretRef
        value:
          secretName: github-webhook-secret
          secretKey: secretToken
      - name: eventTypes
        value: ["push"]
    bindings:
    - ref: github-push
      kind: ClusterTriggerBinding
    template:
      ref: github-push-pipeline

The kind: ClusterTriggerBinding field is required to distinguish the github-push binding from a namespace-scoped TriggerBinding resource with the same name.

The eventTypes: ["push"] interceptor parameter ensures the event listener processes only push events and ignores all other event types, such as pull requests or releases.

Apply the manifest by running the following command:

$ oc apply -f github-push-listener.yaml

Expose the EventListener service as a publicly accessible route:
```
$ oc expose svc el-github-push-listener
```
Get the route URL by running the following command:
```
$ oc get route el-github-push-listener --template='http://{{.spec.host}}'
```
Save the URL displayed in the output. You provide this URL to GitHub when configuring the webhook.
Note
For a production environment, create a secure HTTPS route instead. See "Securing webhooks with event listeners" in the Additional resources section.
Configure a webhook on your GitHub repository to send push events to the EventListener route:
1. Open your GitHub repository in a browser.
2. Click Settings Webhooks Add webhook.
3. On the Add webhook page:
  1. Enter the EventListener route URL from the earlier step in the Payload URL field.
  2. Select application/json for the Content type.
  3. Enter the secret token you set in the github-webhook-secret Secret resource in the Secret field.
  4. Select Just the push event.
  5. Select Active.
  6. Click Add webhook.

Verification

Push a commit to your GitHub repository by running the following commands:
```
$ git commit --allow-empty -m "Test pipeline trigger"
```
```
$ git push
```
List the pipeline runs to confirm that a new run was created:
```
$ tkn pipelinerun list
```
A new PipelineRun with a name prefixed by github-push-run- is displayed in the output within a few seconds of the push event.

6.3. ClusterTriggerBinding reference
Copy link

Red Hat OpenShift Pipelines installs the following ClusterTriggerBinding resources. Each binding extracts parameters from the webhook event payload of the corresponding Git hosting provider. You can reference these bindings in a Trigger or EventListener resource by setting kind: ClusterTriggerBinding.

6.3.1. GitHub ClusterTriggerBindings
Copy link

github-push

Extracts parameters from a GitHub push event payload.

Parameter name	Description	Source (JSONPath)
`git-revision`	SHA of the commit that triggered the push	`$(body.head_commit.id)`
`git-commit-message`	Commit message of the pushed commit	`$(body.head_commit.message)`
`git-repo-url`	GitHub REST API URL of the repository. This is not a clone URL and cannot be used directly with `git-clone`. Use `git-repo-clone-url` instead when you need to clone the repository.	`$(body.repository.url)`
`git-repo-clone-url`	HTTPS URL of the repository, suitable for cloning. Use this parameter with `git-clone` and similar tasks.	`$(body.repository.html_url)`
`git-repo-name`	Name of the repository	`$(body.repository.name)`
`content-type`	Content type of the HTTP request	`$(header.Content-Type)`
`pusher-name`	GitHub username of the pusher	`$(body.pusher.name)`

github-pullreq

Extracts parameters from a GitHub pull request event payload.

Parameter name	Description	Source (JSONPath)
`git-repo-url`	HTML URL of the repository	`$(body.repository.html_url)`
`pullreq-sha`	SHA of the head commit of the pull request	`$(body.pull_request.head.sha)`
`pullreq-action`	Action that triggered the event, for example `opened` or `closed`	`$(body.action)`
`pullreq-number`	Pull request number	`$(body.number)`
`pullreq-repo-full_name`	Full name of the repository, in `<owner>/<repo>` format	`$(body.repository.full_name)`
`pullreq-html-url`	HTML URL of the pull request	`$(body.pull_request.html_url)`
`pullreq-title`	Title of the pull request	`$(body.pull_request.title)`
`pullreq-issue-url`	Issue API URL associated with the pull request	`$(body.pull_request.issue_url)`
`organisations-url`	URL of the pull request author’s organizations	`$(body.pull_request.user.organizations_url)`
`user-type`	Type of the pull request author, for example `User` or `Bot`	`$(body.pull_request.user.type)`

github-pullreq-review-comment

Extracts parameters from a GitHub pull request review comment event payload.

Parameter name	Description	Source (JSONPath)
`comment`	Body of the review comment	`$(body.comment.body)`
`comment-user-login`	GitHub username of the comment author	`$(body.comment.user.login)`
`merge-commit-sha`	SHA of the merge commit for the pull request	`$(body.pull_request.merge_commit_sha)`

6.3.2. GitLab ClusterTriggerBindings
Copy link

gitlab-push

Extracts parameters from a GitLab push event payload.

Parameter name	Description	Source (JSONPath)
`git-revision`	SHA of the latest commit in the push	`$(body.checkout_sha)`
`git-commit-message`	Commit message of the first commit in the push	`$(body.commits[0].message)`
`git-repo-url`	HTTP clone URL of the repository	`$(body.repository.git_http_url)`
`git-repo-ssh-url`	SSH clone URL of the repository	`$(body.repository.git_ssh_url)`
`git-repo-name`	Name of the repository	`$(body.repository.name)`
`pusher-name`	GitLab username of the pusher	`$(body.user_name)`

gitlab-mergereq

Extracts parameters from a GitLab merge request event payload.

Parameter name	Description	Source (JSONPath)
`git-repo-url`	HTTP clone URL of the project	`$(body.project.git_http_url)`
`git-repo-ssh-url`	SSH clone URL of the repository	`$(body.repository.git_ssh_url)`
`mergereq-sha`	SHA of the last commit in the merge request	`$(body.object_attributes.last_commit.id)`
`mergereq-action`	Action that triggered the event, for example `open` or `merge`	`$(body.object_attributes.action)`
`mergereq-number`	Internal ID of the merge request	`$(body.object_attributes.iid)`
`mergereq-repo-name`	Name of the repository	`$(body.repository.name)`
`mergereq-url`	URL of the merge request	`$(body.object_attributes.url)`
`mergereq-title`	Title of the merge request	`$(body.object_attributes.title)`

gitlab-review-comment-on-issues

Extracts parameters from a GitLab comment event on an issue.

Parameter name	Description	Source (JSONPath)
`issue-url`	URL of the issue	`$(body.issue.url)`
`issue-title`	Title of the issue	`$(body.issue.title)`
`issue-comment-link`	URL of the comment	`$(body.object_attributes.url)`
`issue-owner`	Name of the comment author	`$(body.user.name)`

gitlab-review-comment-on-mergerequest

Extracts parameters from a GitLab comment event on a merge request.

Parameter name	Description	Source (JSONPath)
`mergereq-url`	URL of the merge request	`$(body.merge_request.url)`
`comment-description`	Body of the comment	`$(body.object_attributes.description)`
`comment-url`	URL of the comment	`$(body.object_attributes.url)`
`mr-owner`	Name of the comment author	`$(body.user.name)`

gitlab-review-comment-on-commit

Extracts parameters from a GitLab comment event on a commit.

Parameter name	Description	Source (JSONPath)
`commit-url`	URL of the commit	`$(body.commit.url)`
`comment-description`	Body of the comment	`$(body.object_attributes.description)`
`comment-url`	URL of the comment	`$(body.object_attributes.url)`
`commit-owner`	Name of the comment author	`$(body.user.name)`

gitlab-review-comment-on-snippet

Extracts parameters from a GitLab comment event on a snippet.

Parameter name	Description	Source (JSONPath)
`snippet-comment-description`	Body of the comment	`$(body.object_attributes.description)`
`snippet-comment-url`	URL of the comment	`$(body.object_attributes.url)`
`snippet-title`	Title of the snippet	`$(body.snippet.title)`
`snippet-type`	Type of the snippet	`$(body.snippet.type)`
`snippet-owner`	Name of the comment author	`$(body.user.name)`

6.3.3. Bitbucket Server ClusterTriggerBindings
Copy link

bitbucket-push

Extracts parameters from a Bitbucket Server push event payload.

Parameter name	Description	Source (JSONPath)
`git-revision`	Display ID of the reference that was pushed, for example a branch name	`$(body.changes[0].ref.displayId)`
`gitrepo-url`	Clone URL of the repository	`$(body.repository.links.clone[0].href)`
`git-repo-name`	Name of the repository	`$(body.repository.name)`
`pusher-name`	Username of the pusher	`$(body.actor.name)`

bitbucket-pullreq

Extracts parameters from a Bitbucket Server pull request event payload.

Parameter name	Description	Source (JSONPath)
`gitrepo-url`	SSH clone URL of the source repository	`$(body.pullRequest.fromRef.repository.links.clone[?(@.name=="ssh")].href)`
`pullreq-sha`	Latest commit SHA of the source branch	`$(body.pullRequest.fromRef.latestCommit)`
`pullreq-state`	State of the pull request, for example `OPEN` or `MERGED`	`$(body.pullRequest.state)`
`pullreq-number`	ID of the pull request	`$(body.pullRequest.id)`
`pullreq-repo-name`	Name of the target repository	`$(body.pullRequest.toRef.repository.name)`
`pullreq-html-url`	Web URL of the pull request	`$(body.pullRequest.links.self[0].href)`
`pullreq-title`	Title of the pull request	`$(body.pullRequest.title)`
`user-type`	Type of the pull request author	`$(body.pullRequest.author.user.type)`

bitbucket-pullreq-add-comment

Extracts parameters from a Bitbucket Server pull request comment event payload.

Parameter name	Description	Source (JSONPath)
`comment`	Text of the comment	`$(body.comment.text)`
`comment-user-login`	Username of the comment author	`$(body.comment.author.name)`

6.3.4. Bitbucket Cloud ClusterTriggerBindings
Copy link

bitbucket-cloud-push

Extracts parameters from a Bitbucket Cloud push event payload.

Parameter name	Description	Source (JSONPath)
`git-revision`	Name of the branch or tag that was pushed	`$(body.push.changes[0].new.name)`
`gitrepo-url`	HTML URL of the repository	`$(body.repository.links.html.href)`
`git-repo-name`	Name of the repository	`$(body.repository.name)`
`pusher-name`	Display name of the pusher	`$(body.actor.display_name)`

bitbucket-cloud-pullreq

Extracts parameters from a Bitbucket Cloud pull request event payload.

Parameter name	Description	Source (JSONPath)
`gitrepo-url`	HTML URL of the source repository	`$(body.pullrequest.source.repository.links.html.href)`
`pullreq-sha`	Commit hash of the source branch head	`$(body.pullrequest.source.commit.hash)`
`pullreq-state`	State of the pull request, for example `OPEN` or `MERGED`	`$(body.pullrequest.state)`
`pullreq-number`	ID of the pull request	`$(body.pullrequest.id)`
`pullreq-repo-name`	Name of the destination repository	`$(body.pullrequest.destination.repository.name)`
`pullreq-html-url`	HTML URL of the pull request	`$(body.pullrequest.links.html.href)`
`pullreq-title`	Title of the pull request	`$(body.pullrequest.title)`
`user-type`	Display name of the pull request author	`$(body.pullrequest.author.display_name)`

bitbucket-cloud-pullreq-add-comment

Extracts parameters from a Bitbucket Cloud pull request comment event payload.

Parameter name	Description	Source (JSONPath)
`comment`	Raw text of the comment	`$(body.comment.content.raw)`
`comment-user-login`	Display name of the comment author	`$(body.comment.user.display_name)`
`pullreq-number`	ID of the pull request the comment belongs to	`$(body.comment.pullrequest.id)`

Chapter 6. Using ClusterTriggerBindings with OpenShift Pipelines

6.1. ClusterTriggerBindings overview
Copy link

6.2. Triggering a pipeline run from a GitHub push event
Copy link

6.3. ClusterTriggerBinding reference
Copy link

6.3.1. GitHub ClusterTriggerBindings
Copy link

6.3.2. GitLab ClusterTriggerBindings
Copy link

6.3.3. Bitbucket Server ClusterTriggerBindings
Copy link

6.3.4. Bitbucket Cloud ClusterTriggerBindings
Copy link

Learn

Try, buy, & sell

Communities

About Red Hat

Making open source more inclusive

About Red Hat Documentation

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 6. Using ClusterTriggerBindings with OpenShift Pipelines

6.1. ClusterTriggerBindings overviewCopy linkLink copied to clipboard!

6.2. Triggering a pipeline run from a GitHub push eventCopy linkLink copied to clipboard!

6.3. ClusterTriggerBinding referenceCopy linkLink copied to clipboard!

6.3.1. GitHub ClusterTriggerBindingsCopy linkLink copied to clipboard!

6.3.2. GitLab ClusterTriggerBindingsCopy linkLink copied to clipboard!

6.3.3. Bitbucket Server ClusterTriggerBindingsCopy linkLink copied to clipboard!

6.3.4. Bitbucket Cloud ClusterTriggerBindingsCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat

Making open source more inclusive

About Red Hat Documentation

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

6.1. ClusterTriggerBindings overview
Copy link

6.2. Triggering a pipeline run from a GitHub push event
Copy link

6.3. ClusterTriggerBinding reference
Copy link

6.3.1. GitHub ClusterTriggerBindings
Copy link

6.3.2. GitLab ClusterTriggerBindings
Copy link

6.3.3. Bitbucket Server ClusterTriggerBindings
Copy link

6.3.4. Bitbucket Cloud ClusterTriggerBindings
Copy link