GitHub Simple Interceptor
This interceptor aims to provide simplified configuration for GitHub repository
triggers. It is heavily motivated by the existing
add-pr-body
and
add-team-members
interceptors, but provides a more opinionated strategy to simplify the config
needed to be set by users.
Configuration
This interceptor expects its configuration in an InterceptorParam named
config
. The full config spec (including defaults) can be found at
pkg/proto/v1alpha1/config.proto
[./pkg/proto/v1alpha1/config.proto].
Pull Request Approvers
To gate pull request runs on OWNER approval, users can specify the comment
field in their configuration to require OWNERS to comment on the pull request
in order for the test to run. By default, the interceptor looks for a file named
OWNERS
in the top level directory of the repo, and expects the comment
/ok-to-test
(these can be modified).
For compatibility with existing Prow setups, the interceptor expects the OWNERS
file to match the Prow OWNERS config format
(https://www.kubernetes.dev/docs/guide/owners). Any approver
or reviewer
is
allowed to trigger pull request runs via comment. NOTE: filters are not
yet supported.
Deployment
-
Generate the secret
$ openssl rand -base64 32 > /tmp/webhook.txt
-
Create/Update GitHub webhook using secret (see
Securing your webhooks)
-
Generate Kubernetes Secret
$ kubectl create secret generic github-webhook-secret --from-file=/tmp/webhook.txt
-
Deploy interceptor
$ ko apply -f config
Cookbook
Allow all pushes, pull requests
interceptors:
- ref:
name: "github-simple"
params:
- name: config
value:
push:
pull_request:
This config will allow pushes to any branch or tag, pull requests to any branch.
Allow all, require approver sign off
interceptors:
- ref:
name: "github-simple"
params:
- name: config
value:
push:
pull_request:
comment:
This config will allow pushes to any branch or tag, pull requests to any branch,
but requires pull requests to be approved by users in the OWNERS
file in the
repo's default branch before they are ran.
Full Example:
interceptors:
- ref:
name: "github-simple"
params:
- name: config
value:
push:
ref: ["refs/heads/*", "refs/tags/*"]
pull_request:
branch: ["*"]
comment:
approvers:
path: "OWNERS"
revision: "main"
match: "/ok-to-test"
This is the same as the previous example, but explicitly configures all the
default fields.
Extensions
This interceptor will provide the following extension outputs that can be used
in TriggerTemplates.
These values are intended to be recommended defaults. If you wish to use
different values, simply specify the desired values in your Trigger binding.
git
These extension values provide information on what Git source to checkout as
part of the build. This data aims to be VCS agnostic.
key |
value |
url |
URL suitable for use with a git clone operation |
revision |
Recommended Git revision to build/test against. For pushes this is the new ref SHA. For pull requests this is the revision of the pull request head (this does not provide the merge SHA, since this is not guaranteed to be populated at trigger runtime) |
github
These extension values provide information on what GitHub
repository/installation we are operating on.
pull_request
For pull request related events (pull request updates, comments), the
GitHub Pull Request API object
will be embedded.