#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 because the App owns webhook delivery.
• 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. When automatic webhook registration is enabled, the webhook registration controller creates or updates the repository webhook for you.

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 is recorded in pipelines-as-code-info.data.controller-url. See Get the PAC Webhook URL for setup and verification.
• Admin access to the GitHub repository, a token with permission to manage repository webhooks, or access 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. In GitHub App mode, only the repository URL is required because the App-level webhook delivers events to PAC.

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 annotation grammar, and Trigger PAC Pipelines for automatic and comment-based triggers.

#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 Repository-local token permissions required by GitHub. This token is used by PAC to read repository data and report pipeline results. It does not need webhook management permission when a centralized webhook registration credential is configured.

For automatic webhook registration, configure a matching centralized credential with admin:repo_hook for a classic PAT, or target repository Webhooks write permission for a fine-grained PAT. See Centralized webhook registration token.

#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:
    type: github
    secret:
      name: github-webhook-config
    webhook_secret:
      name: github-webhook-config

Apply it:

kubectl apply -f repository.yaml

For GitHub Enterprise, set git_provider.url to the Enterprise API URL:

spec:
  url: https://github.example.com/<owner>/<repo>
  git_provider:
    type: github
    url: https://github.example.com/api/v3
    secret:
      name: github-webhook-config
    webhook_secret:
      name: github-webhook-config

#Step 4: Verify automatic webhook registration

After the Repository is created, the webhook registration controller watches it and registers a GitHub repository webhook. Check the Repository annotations and events:

kubectl describe repository my-repo -n project-pipelines
kubectl get repository my-repo -n project-pipelines \
  -o jsonpath='{.metadata.annotations.pac\.tekton\.alauda\.io/webhook-registration-status}'

Expected status is Registered. The controller creates or updates a GitHub web hook with:

• Payload URL: the public PAC webhook URL
• Content type: application/json
• Secret: the webhook.secret value referenced by spec.git_provider.webhook_secret
• Events: commit comments, issue comments, pull requests, and pushes
• SSL verification: enabled by default

The controller records the GitHub hook ID in pac.tekton.alauda.io/webhook-managed-ref. If the PAC webhook URL changes later, the controller updates the recorded hook by ID instead of creating a duplicate hook for the same repository.

To exclude one Repository from automatic webhook registration, add this label to the Repository metadata:

metadata:
  labels:
    pac.tekton.alauda.io/webhook-registration-disabled: "true"

#Manual fallback

If automatic registration is disabled or cannot be used, register the webhook manually:

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 PAC 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 PAC Pipelines — automatic events and comment commands.
• Advanced Repository Configuration — concurrency, parameters, custom settings.
• Configure Custom Certificates — for GitHub Enterprise with a private CA.