Incoming webhook #
Pipelines as Code support the concept of incoming webhook URL. It let you trigger PipelineRun in a Repository using a shared secret and URL, instead of creating a new code iteration.
Incoming Webhook URL #
To use incoming webhooks in Pipelines as Code, you must configure the
incoming field in your Repository CRD. This field references a Secret
, which
serves as the shared secret, as well as the branches targeted by the incoming
webhook. Once configured, Pipelines as Code will match PipelineRuns
located in
your .tekton
directory if the on-event
annotation of the targetted pipelinerun is
targettting a push or incoming event.
If you are not using the github app provider (ie: webhook based provider) you will need to have a
git_provider
spec to specify a token.Additionally since we are not able to detect automatically the type of provider on URL. You will need to add it to the
git_provider.type
spec. Supported values are:
- github
- gitlab
- bitbucket-cloud
Whereas for
github-apps
this doesn’t need to be added.
GithubApp #
The example below illustrates the use of GithubApp to trigger a PipelineRun based on an incoming webhook URL.
The Repository Custom Resource (CR) specifies the target branch as
main and includes an incoming webhook URL with a shared password stored in a
Secret called repo-incoming-secret
:
---
apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
name: repo
namespace: ns
spec:
url: "https://github.com/owner/repo"
incoming:
- targets:
- main
secret:
name: repo-incoming-secret
type: webhook-url
A PipelineRun is then annotated to target the incoming event and the main branch:
apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
name: target_pipelinerun
annotations:
pipelinesascode.tekton.dev/on-event: "[incoming]"
pipelinesascode.tekton.dev/on-target-branch: "[main]"
A secret called repo-incoming-secret is utilized as a shared password to ensure
that only authorized users can initiate the PipelineRun
:
apiVersion: v1
kind: Secret
metadata:
name: repo-incoming-secret
namespace: ns
type: Opaque
stringData:
secret: very-secure-shared-secret
After setting this up, you will be able to start the PipelineRun with a POST request sent to the controller URL appended with /incoming. The request includes the very-secure-shared-secret, the repository name (repo), the target branch (main), and the PipelineRun name (target_pipelinerun).
As an example here is a curl snippet starting the PipelineRun:
curl -X POST 'https://control.pac.url/incoming?secret=very-secure-shared-secret&repository=repo&branch=main&pipelinerun=target_pipelinerun'
in this snippet, note two things the "/incoming"
path to the controller URL
and the "POST"
method to the URL rather than a simple "GET"
.
It is important to note that when the PipelineRun is triggered, Pipelines as Code will treat it as a push event and will have the capabilty to report the status of the PipelineRuns. To obtain a report or a notification, a finally task can be added directly to the Pipeline, or the Repo CRD can be inspected using the tkn pac CLI. The statuses documentation provides guidance on how to achieve this.
Webhook methods (GitHub Webhook, Gitlab, Bitbucket etc..) #
Here is an example of a Repository CRD matching the target branch main:
---
apiVersion: "pipelinesascode.tekton.dev/v1alpha1"
kind: Repository
metadata:
name: repo
namespace: ns
spec:
url: "https://github.com/owner/repo"
git_provider:
type: github
secret:
name: "owner-token"
incoming:
- targets:
- main
secret:
name: repo-incoming-secret
type: webhook-url
As noted in the section above, you need to specify a incoming secret inside
the repo-incoming-secret
Secret.