#Configure GitHub Repository

This guide connects a GitHub repository to PAC, end to end: choosing an integration mode, preparing the credentials, creating the Repository resource, and registering the webhook.

PAC supports two ways to integrate with GitHub:

• GitHub App — a single GitHub App is installed on the GitHub organization (or user) once by an administrator. Each repository that belongs to the installation is then represented by a Repository resource with only the URL; no per-repository token or webhook needs to be configured.
• Webhook — a Personal Access Token and a webhook are configured per repository. Suitable when you do not own the GitHub organization or cannot install an App.

The two modes are mutually exclusive for a given Repository resource.

#Prerequisites

• PAC component deployed and exposed; see Manage PAC Component.
• The PAC webhook URL; see Get the PAC Webhook URL.
• Admin access to the GitHub repository (to add a webhook) or to the GitHub organization (to install an App).
• A target Kubernetes namespace where the Repository resource and its PipelineRuns will live.
• kubectl access to that namespace.
• tkn CLI with the pac plugin installed if you use tkn pac bootstrap; see tkn pac Command Reference.

#Choose an integration mode

Use the GitHub App mode when you administer the GitHub organization and intend to onboard many repositories. Use the Webhook mode for a one-off repository, for repositories outside your organization, or when an App installation is not possible.

#Integration mode 1: GitHub App

#How it works

A GitHub App, installed once on a GitHub organization or user, sends events for every repository in the installation to the PAC controller. PAC authenticates back to GitHub on behalf of the App. The Kubernetes-side credentials (App ID, private key, webhook secret) live in a cluster-wide Secret in the PAC namespace; you do not put any per-repository credentials in the user namespace.

#Step 1 (admin): Create and install the GitHub App

This step is done once per cluster, by a cluster administrator.

#Option A: Use tkn pac bootstrap

tkn pac bootstrap walks through GitHub App creation and stores the resulting credentials in the cluster Secret:

tkn pac bootstrap

Follow the prompts. The command creates the App, generates the private key, and creates the pipelines-as-code-secret Secret in the PAC namespace.

#Option B: Create the GitHub App manually

1. Go to GitHub → Settings → Developer settings → GitHub Apps and click New GitHub App.

2. Fill in the form:

   • GitHub App name: any descriptive name, for example Alauda DevOps Pipelines.
   • Homepage URL: a URL of your choice, for example the platform console URL.
   • Webhook URL: the PAC webhook URL from the prerequisites.
   • Webhook secret: any random string. Save it; you will store it in Kubernetes in the next step.

3. Set the Repository permissions:

   Permission	Access
   Checks	Read & Write
   Contents	Read & Write
   Issues	Read & Write
   Metadata	Read-only
   Pull requests	Read & Write

4. Set the Organization permissions:

   Permission	Access
   Members	Read-only

5. Subscribe to events: Check run, Check suite, Commit comment, Issue comment, Pull request, Push.

6. Click Create GitHub App.

7. On the App detail page, note the App ID.

8. In Private keys, click Generate a private key and save the downloaded .pem file.

Install the App: from the App page, click Install App and select the organization or user and the repositories you want PAC to handle.

#Step 2 (admin): Store the GitHub App credentials in Kubernetes

Create a Secret in the PAC namespace that holds the App ID, the private key, and the webhook secret. Replace <pac-namespace> (default tekton-pipelines), <app-id>, <webhook-secret> and <path-to-private-key>:

kubectl -n <pac-namespace> create secret generic pipelines-as-code-secret \
  --from-literal github-application-id='<app-id>' \
  --from-literal webhook.secret='<webhook-secret>' \
  --from-file github-private-key='<path-to-private-key>'

PAC reads this Secret on every incoming event. No controller restart is required.

#Step 3 (user): Create the Repository resource

Once the App is installed on the GitHub repository, a regular user creates a minimal Repository resource in their namespace. Only the repository URL is required; no git_provider block is needed.

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://github.com/<owner>/<repo>

Apply it:

kubectl apply -f repository.yaml

Verify:

kubectl get repositories -n project-pipelines

Example output:

NAME      URL                                  SUCCEEDED   REASON   STARTTIME   COMPLETIONTIME
my-repo   https://github.com/owner/repo

#Step 4 (user): Add a PipelineRun and trigger it

Add a PipelineRun manifest under .tekton/ in the repository and push it. PAC will pick the event up and create a PipelineRun in the namespace. See Define PipelineRuns in Git for the file layout and the annotation grammar, and Trigger Pipelines for the Git operations that PAC reacts to.

#Integration mode 2: Webhook

#How it works

A Personal Access Token and a webhook are configured directly on a single GitHub repository. PAC uses the token to read repository metadata and to publish commit statuses; the webhook secret is shared between GitHub and the cluster so PAC can verify the origin of each event.

#Step 1: Create a Personal Access Token

Follow Create a Git Secret for PAC for the scopes required by GitHub. In short, a classic Personal Access Token with the repo scope (or public_repo for public repositories only) is enough.

#Step 2: Create the Kubernetes Secret

Create a Secret carrying both the Git access token and a webhook secret. See Create a Git Secret for PAC for the procedure.

In the rest of this guide the Secret is named github-webhook-config.

#Step 3: Create the Repository resource

Reference the Secret from the Repository:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: my-repo
  namespace: project-pipelines
spec:
  url: https://github.com/<owner>/<repo>
  git_provider:
    secret:
      name: github-webhook-config
    webhook_secret:
      name: github-webhook-config

Apply it:

kubectl apply -f repository.yaml

#Step 4: Register the webhook in GitHub

1. Open the GitHub repository, then Settings → Webhooks → Add webhook.
2. Fill in the form:
   • Payload URL: the PAC webhook URL from the prerequisites.
   • Content type: application/json.
   • Secret: the same webhook.secret value stored in the Kubernetes Secret.
   • SSL verification: enabled (recommended).
3. Under Which events would you like to trigger this webhook?, select Let me select individual events and check:
   • Commit comments
   • Issue comments
   • Pull requests
   • Pushes
4. Click Add webhook.

GitHub immediately sends a ping event. A green tick on the webhook entry confirms PAC accepted it.

#Step 5: Add a PipelineRun and trigger it

Same as the App mode: add a PipelineRun under .tekton/ in the repository. See Define PipelineRuns in Git and Trigger Pipelines.

#Verification

After a Git event arrives, PAC creates a PipelineRun in the Repository's namespace. Confirm:

kubectl get pipelineruns -n project-pipelines \
  -l pipelinesascode.tekton.dev/repository=my-repo

The PAC controller logs show the event being processed:

kubectl logs -n <pac-namespace> -l app=pipelines-as-code-controller --tail=100

For status reporting, GitHub displays:

• In App mode: a Check Run on the commit, with detailed step output.
• In Webhook mode: a commit status linking back to the cluster.

#Troubleshooting

For the full troubleshooting matrix, see Common Issues.

#Next steps

• Define PipelineRuns in Git — define and evolve pipelines under .tekton/.
• Trigger Pipelines — push, pull request and comment-driven triggers.
• Advanced Repository Configuration — concurrency, parameters, custom settings.
• Configure Custom Certificates — for GitHub Enterprise with a private CA.