tkn pac webhook

Manage webhook configuration for Pipelines-as-Code repositories including secrets and provider tokens.

Available Commands

add - Add webhook secret and configure on Git provider
update-token - Update provider token in existing secret

add

Add a new webhook secret for a Git provider and configure it on the provider settings.

Synopsis

tkn pac webhook add [repository-name] [flags]

Description

The webhook add command:

Selects a repository (prompts if not specified)
Detects Git provider (GitHub, GitLab, Bitbucket, etc.)
Prompts for credentials (personal access token, webhook secret)
Creates Kubernetes secrets for authentication
Configures webhook on the Git provider
Updates Repository CRD with secret references

This command is useful for:

Repositories not using GitHub App
Adding webhooks to existing repositories
Reconfiguring webhook secrets

If using GitHub App, webhook configuration is automatic. This command is not needed.

Usage Examples

# Select repository interactively
tkn pac webhook add

Arguments

repository-name

string

Repository name (optional - prompts if not provided)

Flags

-n, --namespace

string

Namespace containing the repository

--pac-namespace

string

Namespace where Pipelines-as-Code is installed

Interactive Flow

1. Repository Selection

If not specified:

? Select a repository:
  › myorg-api
    myorg-frontend
    myorg-docs

2. Provider Detection

Automatically detected from repository URL:

Detected provider: GitHub

3. Personal Access Token

? Enter your personal access token: ****

4. Webhook Secret

? Enter webhook secret (leave empty to auto-generate):

If left empty, a secure random secret is generated.

5. Webhook Configuration

✓ Webhook configured on https://github.com/myorg/app
✓ Secret git-provider-secret has been created
✓ Secret webhook-secret has been created
✓ Repository myorg-app has been updated

Output Example

$ tkn pac webhook add myorg-app

Detected provider: GitHub

? Enter your personal access token: ****
? Enter webhook secret (leave empty to auto-generate): 

✓ Webhook configured on https://github.com/myorg/app
  Webhook ID: 123456789
  Events: push, pull_request, issue_comment

✓ Secret git-provider-secret has been created in production namespace
✓ Secret webhook-secret has been created in production namespace
✓ Repository myorg-app has been updated with secret references

Provider-Specific Requirements

GitHub

Token Scopes Required:

repo - Full control of private repositories
admin:repo_hook - Write access to repository hooks

Create Token:

Go to Settings → Developer settings → Personal access tokens
Generate new token (classic)
Select required scopes
Copy token

GitLab

Token Scopes Required:

api - Full API access
read_repository - Read repository

Create Token:

Go to Preferences → Access Tokens
Create personal access token
Select required scopes
Copy token

Bitbucket Cloud

App Password Required:

repository:write - Write access to repositories
webhook - Manage webhooks

Create App Password:

Go to Personal settings → App passwords
Create app password
Select required permissions
Copy password

Bitbucket Server/Data Center

Token Required:

REPO_ADMIN - Repository administration

Create Token:

Go to Personal settings → Personal access tokens
Create token with REPO_ADMIN
Copy token

Created Secrets

Two Kubernetes secrets are created:

git-provider-secret

apiVersion: v1
kind: Secret
metadata:
  name: git-provider-secret
  namespace: production
type: Opaque
data:
  token: <base64-encoded-token>

webhook-secret

apiVersion: v1
kind: Secret
metadata:
  name: webhook-secret
  namespace: production
type: Opaque
data:
  webhook-secret: <base64-encoded-secret>

Repository CRD Update

The Repository is updated with secret references:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
  name: myorg-app
spec:
  url: "https://github.com/myorg/app"
  git_provider:
    secret:
      name: "git-provider-secret"
      key: "token"
    webhook_secret:
      name: "webhook-secret"
      key: "webhook-secret"

Webhook Configuration on Provider

The webhook is configured with: Payload URL:

https://<pac-controller-url>/incoming

Events:

Push
Pull Request
Issue Comment (for /test, /retest commands)

Content Type:

application/json

Secret: The webhook secret for payload validation

Troubleshooting

GitHub App Already Configured:

✓ Repository myorg-app has been created in production namespace
✓ A basic template has been created in .tekton/pipelinerun.yaml

If GitHub App is configured, webhooks are automatic. No action needed. Invalid Token:

Error: failed to create webhook: 401 Unauthorized

Solution: Verify token has correct scopes and is not expired. Webhook Already Exists:

Error: webhook already exists for this URL

Solution: Delete existing webhook from provider settings or update it. Cannot Access Repository:

Error: failed to access repository: 404 Not Found

Solutions:

Verify repository URL is correct
Ensure token has access to the repository
Check repository visibility (private vs public)

update-token

Update the provider token in an existing webhook secret.

Synopsis

tkn pac webhook update-token [repository-name] [flags]

Description

The update-token command updates the personal access token or API key in an existing Git provider secret. This is useful when:

Token has expired
Token was rotated for security
Need to use a different account
Changing token scopes

This command only updates the token, not the webhook configuration. The webhook on the Git provider remains unchanged.

Usage Examples

# Select repository interactively
tkn pac webhook update-token

Arguments

repository-name

string

Repository name (optional - prompts if not provided)

Flags

-n, --namespace

string

Namespace containing the repository

Interactive Flow

1. Repository Selection

? Select a repository:
  › myorg-api
    myorg-frontend
    myorg-docs

2. Token Input

? Please enter your personal access token: ****

3. Confirmation

🔑 Secret git-provider-secret has been updated with new personal access token in the production namespace.

Output Example

$ tkn pac webhook update-token myorg-app

? Please enter your personal access token: ****

🔑 Secret git-provider-secret has been updated with new personal access token in the production namespace.

When to Update Token

Token Expired
```
Error on PipelineRun: 401 Unauthorized
```

Token Revoked

Cannot access repository: token is no longer valid

Security Rotation
- Regular security practice
- After team member leaves
- Suspected compromise
Scope Changes
- Need additional permissions
- Reduce token privileges

Common Workflows

Rotate Expired Token

# Generate new token from provider
# Then update:
tkn pac webhook update-token myorg-app

Update Multiple Repositories

# Update token for all repositories using same token
tkn pac webhook update-token api-repo
tkn pac webhook update-token frontend-repo
tkn pac webhook update-token docs-repo

Security Incident Response

# Revoke compromised token on provider
# Generate new token
# Update all affected repositories
tkn pac webhook update-token myorg-app

Troubleshooting

Webhook Not Configured:

ℹ️ Webhook is not configured for the repository myorg-app

Solution: Use tkn pac webhook add first to configure webhook. GitHub App Configured:

Webhook is not configured for the repository myorg-app

If using GitHub App, tokens are managed by the app. This command is not applicable. Empty Secret:

⚠️ Can not update provider token when git_provider secret is empty

Solution: The repository configuration is incomplete. Use tkn pac webhook add to configure properly. Secret Not Found:

Error: secrets "git-provider-secret" not found

Solution: Secret was deleted. Use tkn pac webhook add to recreate. Permission Denied:

Error: secrets is forbidden

Solution: Request RBAC permissions to update secrets in the namespace.

Verification

After updating token, verify it works:

# Trigger a test run
git commit --allow-empty -m "test: verify new token"
git push

# Check logs
tkn pac logs myorg-app --last

tkn pac create repo - Create repository with webhook
tkn pac bootstrap - Bootstrap with GitHub App
tkn pac list - List repositories

Overview

Commands

​tkn pac webhook

​Available Commands

​add

​Synopsis

​Description

​Usage Examples

​Arguments

​Flags

​Interactive Flow

​1. Repository Selection

​2. Provider Detection

​3. Personal Access Token

​4. Webhook Secret

​5. Webhook Configuration

​Output Example

​Provider-Specific Requirements

​GitHub

​GitLab

​Bitbucket Cloud

​Bitbucket Server/Data Center

​Created Secrets

​git-provider-secret

​webhook-secret

​Repository CRD Update

​Webhook Configuration on Provider

​Troubleshooting

​update-token

​Synopsis

​Description

​Usage Examples

​Arguments

​Flags

​Interactive Flow

​1. Repository Selection

​2. Token Input

​3. Confirmation

​Output Example

​When to Update Token

​Common Workflows

​Rotate Expired Token

​Update Multiple Repositories

​Security Incident Response

​Troubleshooting

​Verification

​Related Commands

​See Also

Build docs developers (and LLMs) love

tkn pac webhook

Available Commands

add

Synopsis

Description

Usage Examples

Arguments

Flags

Interactive Flow

1. Repository Selection

2. Provider Detection

3. Personal Access Token

4. Webhook Secret

5. Webhook Configuration

Output Example

Provider-Specific Requirements

GitHub

GitLab

Bitbucket Cloud

Bitbucket Server/Data Center

Created Secrets

git-provider-secret

webhook-secret

Repository CRD Update

Webhook Configuration on Provider

Troubleshooting

update-token

Synopsis

Description

Usage Examples

Arguments

Flags

Interactive Flow

1. Repository Selection

2. Token Input

3. Confirmation

Output Example

When to Update Token

Common Workflows

Rotate Expired Token

Update Multiple Repositories

Security Incident Response

Troubleshooting

Verification

Related Commands

See Also