Skip to main content

​
tkn pac bootstrap

Bootstrap Pipelines-as-Code installation and GitHub App configuration on your Kubernetes cluster.

​
Synopsis

tkn pac bootstrap [flags]
tkn pac bootstrap github-app [flags]

​
Description

The bootstrap command helps you get started by:
  1. Checking if Pipelines-as-Code is installed
  2. Installing or upgrading PAC if needed
  3. Detecting OpenShift Routes or Kubernetes Ingress
  4. Creating a GitHub App for authentication
  5. Configuring webhook forwarding (if needed)

​
Subcommands

​
tkn pac bootstrap

Full bootstrap process including installation and GitHub App creation.

​
tkn pac bootstrap github-app

Create only the GitHub App, skipping the installation step. Useful when PAC is already installed.

​
Supported Providers

  • GitHub (public github.com)
  • GitHub Enterprise (self-hosted GitHub)

​
Installation Detection

The command automatically:
  • Checks for existing Pipelines-as-Code installation
  • Detects the installation namespace (pipelines-as-code or openshift-pipelines)
  • Offers to install the latest stable or nightly release if not found

​
Route/Ingress Detection

OpenShift:
  • Automatically detects OpenShift Routes
  • Uses the Route URL as the webhook endpoint
Kubernetes:
  • Attempts to detect Tekton Dashboard Ingress
  • Prompts to use detected URL or enter custom URL

​
Webhook Forwarding (gosmee)

For clusters not accessible from the internet, bootstrap can install gosmee, a webhook forwarder:
  • Creates a public URL at https://hook.pipelinesascode.com
  • Forwards webhooks to your cluster
  • Automatically configured in GitHub App
gosmee is for testing only. Do not use in production environments.

​
Usage Examples

# Interactive bootstrap
tkn pac bootstrap

​
Flags

​
Installation Flags

​
--skip-install
boolean
default:"false"
Skip Pipelines-as-Code installation
​
--force-install
boolean
default:"false"
Force PAC installation even if already installed
​
--nightly
boolean
default:"false"
Install the nightly/development build instead of stable release

​
GitHub App Flags

​
--skip-github-app
boolean
default:"false"
Skip creating GitHub application
​
--force-configure
boolean
default:"false"
Override existing GitHub App configuration
​
--github-hostname
string
GitHub Enterprise hostname or API URL (e.g., github.company.com)
​
--github-api-url
string
Deprecated: Use --github-hostname instead
​
--github-application-name
string
Custom name for the GitHub Application
​
--github-application-url
string
Homepage URL for the GitHub Application
​
--github-organization-name
string
Target a GitHub organization instead of user account

​
Network Flags

​
--route-url
string
Public URL for the PAC controller (overrides auto-detection)
​
--force-gosmee
boolean
default:"false"
Force gosmee installation even on OpenShift
​
--web-forwarder-url
string
default:"https://hook.pipelinesascode.com"
gosmee forwarder URL
​
--dashboard-url
string
Full URL to Tekton Dashboard
​
--webserver-port
int
default:"8080"
Local webserver port for GitHub App creation flow

​
General Flags

​
-C, --no-color
boolean
Disable colored output

​
Interactive Flow

When running tkn pac bootstrap interactively, you’ll be prompted for:
  1. Installation confirmation (if PAC not found)
  2. GitHub Enterprise setup (if applicable)
  3. Route/Ingress URL (if not auto-detected)
  4. gosmee installation (if cluster not internet-accessible)
  5. GitHub App details (name, organization)

​
Output Example

$ tkn pac bootstrap
=> Checking if Pipelines-as-Code is installed.
✓ Pipelines as Code is already installed.
=> Detecting OpenShift Route...
✓ Route detected: https://pipelines-as-code-controller-pipelines-as-code.apps.cluster.example.com

=> Creating GitHub Application
🌍 Starting web server on http://localhost:8080
📝 Opening browser to create GitHub App...

✓ GitHub App created successfully!
  App ID: 123456
  App Name: my-pac-app

✓ Secret pipelines-as-code-secret has been created in pipelines-as-code namespace
✓ Configuration complete!

​
GitHub App Creation Process

  1. Local webserver starts on port 8080
  2. Browser opens to GitHub App creation page
  3. App manifest submitted with required permissions
  4. Secret created with App credentials in cluster
  5. Configuration stored in pipelines-as-code namespace

​
GitHub App Permissions

The created GitHub App will have:
  • Repository permissions:
    • Contents: Read & Write
    • Issues: Read & Write
    • Metadata: Read
    • Pull Requests: Read & Write
    • Checks: Read & Write
    • Commit statuses: Read & Write
  • Organization permissions:
    • Members: Read
    • Administration: Read
  • Events subscription:
    • Push
    • Pull Request
    • Issue Comment

​
GitHub Enterprise Setup

For GitHub Enterprise installations: 
tkn pac bootstrap --github-hostname github.company.com
The command will:
  1. Detect it’s not public GitHub
  2. Set provider type to github-enterprise-app
  3. Use the correct API endpoints
  4. Create app on your GitHub Enterprise instance

​
Troubleshooting

​
PAC Already Installed

If PAC is already installed: 
✓ Pipelines as Code is already installed.
👌 Skips bootstrapping GitHub App, as one is already configured.
Use --force-configure to reconfigure: 
tkn pac bootstrap --force-configure

​
Route Not Detected

If auto-detection fails: 
# Specify route manually
tkn pac bootstrap --route-url https://pac.example.com

​
Cluster Not Internet Accessible

For clusters behind firewalls: 
# Use gosmee for webhook forwarding
tkn pac bootstrap --force-gosmee
Or on OpenShift with CRC: 
tkn pac bootstrap --force-gosmee

​
Browser Doesn’t Open

If the browser doesn’t open automatically:
  1. Check the terminal output for the URL
  2. Manually open: http://localhost:8080
  3. Complete the GitHub App creation flow

​
Port Already in Use

If port 8080 is busy: 
tkn pac bootstrap --webserver-port 8081

​
Files and Secrets Created

​
Secret: pipelines-as-code-secret

Created in the PAC installation namespace with:
  • github-application-id - GitHub App ID
  • github-private-key - Private key for App authentication
  • webhook.secret - Webhook secret

​
ConfigMap: pipelines-as-code-info

Stores installation metadata:
  • PAC version
  • Installation namespace
  • Controller URL

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us