On this page
GitHub Apps
This page covers how to configure Pipelines-as-Code with a GitHub App. Use this method when you want the richest integration with GitHub, including the CheckRun API, GitOps comments, and automatic token management. A GitHub App is the recommended approach for most GitHub users, and you typically need only one per cluster.
Prerequisites
- A running Pipelines-as-Code installation
- Admin access to a GitHub account or organization
- The public URL of your Pipelines-as-Code controller route or ingress endpoint
Setup using the CLI
Use the tkn pac bootstrap command to create a GitHub App, configure it with your Git repository, and create the required secrets automatically. After creating the GitHub App, install it on the repositories you want to use with Pipelines-as-Code.
If you prefer to configure everything by hand, follow the manual setup steps below.
Manual Setup
To create the GitHub App manually:
Go to https://github.com/settings/apps (or Settings > Developer settings > GitHub Apps) and click on the New GitHub App button
Provide the following information in the GitHub App form:
- GitHub Application Name:
OpenShift Pipelines - Homepage URL: [OpenShift Console URL]
- Webhook URL: [the Pipelines-as-Code route or ingress URL as copied in the previous section]
- Webhook secret: [an arbitrary secret, you can generate one with
head -c 30 /dev/random | base64]
- GitHub Application Name:
Select the following repository permissions:
- Checks:
Read & Write - Contents:
Read & Write - Issues:
Read & Write - Metadata:
Readonly - Pull request:
Read & Write
- Checks:
Select the following organization permissions:
- Members:
Readonly
- Members:
Subscribe to following events:
- Check run
- Check suite
- Commit comment
- Issue comment
- Pull request
- Push
You can see a screenshot of how the GitHub App permissions look like here
Click on Create GitHub App.
Take note of the App ID at the top of the page on the General tab, under About, for the GitHub App you just created.
In the Private keys section, click on Generate Private key to generate a private key for the GitHub app. It downloads automatically. Store the private key in a safe place because you need it in the next section and when reconfiguring this app for a different cluster.
Configure Pipelines-as-Code to access the GitHub App
Pipelines-as-Code needs a Kubernetes secret containing the GitHub App private key and the webhook secret. This secret lets the controller generate tokens on behalf of the user who triggered the event and validate incoming webhook payloads.
Here is how the controller uses that secret for each event:
sequenceDiagram
%% title: How the controller turns a GitHub App event into a token for the PipelineRun
%% autoplay
participant GH as GitHub
participant Ctrl as Controller
participant Sec as pipelines-as-code-secret
participant Run as PipelineRun
GH->>Ctrl: webhook with installation ID
Ctrl->>Sec: read webhook.secret
Ctrl->>Ctrl: verify signature
Ctrl->>Sec: read App ID and private key
Ctrl->>GH: JWT signed with the private key
GH->>Ctrl: installation token
Ctrl->>Ctrl: find Repository CR
Ctrl->>GH: ask for a token limited to the repository
GH->>Ctrl: scoped token
Ctrl->>Run: pac-gitauth secret and PipelineRun
Ctrl->>GH: check run started
%% play: Event to PipelineRun
%% GH -> Ctrl : event | GitHub sends the event, with the ID of the App installation
%% Ctrl -> Sec | The controller reads the webhook secret from its own namespace
%% Ctrl -> Ctrl : HMAC | and refuses the payload when the signature does not match
%% Ctrl -> Sec : private key
%% Ctrl -> GH : JWT | A short lived JWT signed with the private key proves the request comes from the App
%% GH -> Ctrl : token | GitHub answers with an installation token
%% Ctrl -> Ctrl | The controller finds the Repository CR for this repository
%% Ctrl -> GH : repo IDs | It asks for a token limited to this repository, plus any extra repositories from token scoping
%% GH -> Ctrl : token
%% Ctrl -> Run : token | The token goes into a pac-gitauth secret that the PipelineRun can use
%% Ctrl -> GH : check run | Status is reported through the Checks APIRun the following command, replacing the placeholder values:
APP_IDwith the GitHub App App ID copied in the previous sectionWEBHOOK_SECRETwith the webhook secret provided when you created the GitHub AppPATH_PRIVATE_KEYwith the path to the private key that was downloaded in the previous section
kubectl -n pipelines-as-code create secret generic pipelines-as-code-secret \
--from-literal github-private-key="$(cat $PATH_PRIVATE_KEY)" \
--from-literal github-application-id="APP_ID" \
--from-literal webhook.secret="WEBHOOK_SECRET"Finally, install the App on the repositories you want to use with Pipelines-as-Code.
Notes
- GitHub.com requires no additional configuration.
- For a self hosted instance such as GitHub Enterprise Server, the hostname must be trusted by the controller before it will send credentials to it. See Trusted provider hostnames.
Trusting a self hosted GitHub instance
Pipelines-as-Code only sends its Git provider credentials to hostnames it
trusts, listed in the trusted-provider-hostnames key of the controller
ConfigMap (pipelines-as-code by default):
kubectl -n pipelines-as-code patch configmap pipelines-as-code \
--type merge -p '{"data":{"trusted-provider-hostnames":"ghe.example.com"}}'The value is a comma separated list, so several instances can be trusted at once, which is what you want when a single controller serves more than one self hosted provider:
trusted-provider-hostnames: "ghe.example.com, gitlab.example.com"While the key is empty, the public hostnames (github.com, gitlab.com,
bitbucket.org, gitea.com, codeberg.org) stay trusted and the controller
records the hostname of every webhook whose signature it verified in the
pipelinesascode.tekton.dev/auto-trusted-provider-hostnames ConfigMap
annotation. This keeps a default installation working without configuration,
and a controller serving several instances learns all of them.
A non-empty list is authoritative for every hostname, public ones included, and
the controller stops learning hosts. Listing only ghe.example.com is how you
make sure the controller never talks to github.com.
The automatic trust only covers webhooks GitHub signed: incoming webhooks carry no signature and will fail until the hostname is trusted. Setting the key explicitly is therefore the recommended setup for any self hosted instance.
A hostname that is not routable on the public internet (loopback, a private
range, or an in-cluster .svc name) is never recorded automatically: list it
explicitly to trust it.
flowchart LR
%% title: How the controller decides whether to trust a GitHub hostname
Hook@{ img: "/icons/webhook.svg", label: "Signed App webhook", w: 48, h: 48, constraint: "on" }
Inc@{ img: "/icons/terminal.svg", label: "Incoming webhook", w: 48, h: 48, constraint: "on" }
Key@{ img: "/icons/config.svg", label: "Trusted hosts", w: 48, h: 48, constraint: "on" }
Public[Public host]
Learn@{ img: "/icons/audit.svg", label: "Auto-trusted annotation", w: 48, h: 48, constraint: "on" }
Use@{ img: "/icons/unlock.svg", label: "Credentials sent", w: 48, h: 48, constraint: "on" }
No@{ img: "/icons/refuse.svg", label: "Refused", w: 48, h: 48, constraint: "on" }
Hook --> Key
Inc --> Key
Key pub@-->|empty| Public --> Use
Key learn@-->|empty| Learn --> Use
Key listed@-->|listed| Use
Key -->|not trusted| No
%% play: github.com, key empty
%% skip Inc Learn No
%% Hook -> Key : github.com
%% Key -> Public @pub | Public hostnames stay trusted while the key is empty
%% Public -> Use
%% play: Enterprise, key empty
%% skip Inc Public No
%% Hook -> Key : ghe.example.com | The signature was verified with the App webhook secret
%% Key -> Learn @learn | so the controller records the hostname in the ConfigMap annotation
%% Learn -> Use
%% play: Key set
%% skip Inc Public Learn No
%% Hook -> Key : ghe.example.com
%% Key -> Use @listed | A non-empty list decides alone and the controller stops learning hosts
%% play: Key set, host missing
%% skip Inc Public Learn Use
%% Hook -> Key : github.com
%% Key -> No | A host missing from a non-empty list is refused, public ones included
%% play: Incoming webhook
%% skip Hook Public Learn Use
%% Inc -> Key : ghe.example.com | An incoming webhook has no signature, so it never teaches the controller a host
%% Key -> No | Until the host is trusted, the request is refusedIf a hostname is not trusted, the controller refuses the request and logs the exact command to run:
refusing to use credentials with the "ghe.example.com" host: it is not listed in
the "trusted-provider-hostnames" key of the pipelines-as-code/pipelines-as-code
ConfigMap. Add it with: kubectl -n pipelines-as-code patch configmap ...After migrating to a new hostname, replace the value with the new one. Removing a hostname from a non-empty list immediately stops the controller from talking to it. Emptying the key gives the policy back to the controller and makes its previously learned hosts effective again; delete the auto-trusted annotation as well to forget them.
If the controller ConfigMap is managed by GitOps tooling (Argo CD, the
OpenShift Pipelines operator through TektonConfig, …), set
trusted-provider-hostnames in the source of truth. Otherwise a reconciler that
prunes controller-owned annotations makes the controller relearn the hostname
on every signed webhook.