Skip to main content

​
Quickstart guide

Get up and running with Pipelines as Code in just a few minutes using the tkn pac CLI. This guide will walk you through installing the CLI, bootstrapping Pipelines as Code on your cluster, creating a GitHub App, and running your first pipeline.
This guide assumes you’re using the public GitHub instance. If you’re using GitHub Enterprise, you’ll need to use the --github-hostname flag with the hostname of your GitHub Enterprise instance.

​
Prerequisites

Before you begin, make sure you have:

​
Step 1: Install the tkn pac CLI

Choose your preferred installation method: 
brew install openshift-pipelines/pipelines-as-code/tkn-pac
Verify the installation: 
tkn pac version
You should see output similar to: 
Pipelines-as-Code version: v0.x.x

​
Step 2: Bootstrap Pipelines as Code

The tkn pac bootstrap command helps you start using Pipelines as Code quickly by:
  • Installing Pipelines as Code on your cluster (if not already installed)
  • Setting up a webhook forwarder for local development (optional)
  • Creating a GitHub Application
  • Configuring dashboard integration
Run the bootstrap command: 
tkn pac bootstrap

​
Install Pipelines as Code

The CLI will first check if Pipelines as Code is installed: 
=> Checking if Pipelines-as-Code is installed.
🕵️ Pipelines-as-Code doesn't seem to be installed in the pipelines-as-code namespace.
? Do you want me to install Pipelines-as-Code v0.x.x? (Y/n)
Press Y to install it.

​
Set up webhook forwarder (optional)

For local development, you’ll be asked if you want to install gosmee, a webhook forwarder: 
Pipelines-as-Code does not install an Ingress object to allow the controller to be accessed from the internet.
We can install a webhook forwarder called gosmee (https://github.com/chmouel/gosmee) using a https://hook.pipelinesascode.com URL.
? Do you want me to install the gosmee forwarder? (Y/n)
💡 Your gosmee forward URL has been generated: https://hook.pipelinesascode.com/zZVuUUOkCzPD
While gosmee lets you get started quickly, it is not intended for production use. For production, you should set up a proper Ingress or Route to expose the Pipelines as Code webhook endpoint.

​
Configure dashboard (optional)

If you have the Tekton Dashboard installed, the CLI will detect it: 
👀 We have detected a tekton dashboard install on http://dashboard.paac-127-0-0-1.nip.io
? Do you want me to use it? Yes
Press Y to use it for viewing pipeline logs and status.

​
Step 3: Create a GitHub Application

The bootstrap command will now help you create a GitHub Application: 
? Enter the name of your GitHub application: My PAAC Application
Enter a unique name for your GitHub Application (this name must be globally unique across all GitHub Apps).
The CLI will launch your web browser with a URL to create the GitHub Application. Click the button and you’ll be redirected to GitHub.
On GitHub, you’ll see the application creation screen. Unless you want to change the name, click the “Create GitHub App” button. Return to your terminal where you’ll see: 
🔑 Secret pipelines-as-code-secret has been created in the pipelines-as-code namespace
🚀 You can now add your newly created application to your repository by going to this URL:

https://github.com/apps/my-paac-application

💡 Don't forget to run "tkn pac create repository" to create a new Repository CR on your cluster.

​
Step 4: Create a GitHub repository

If you don’t have a repository, you can create one from our template:
  1. Go to https://github.com/openshift-pipelines/pac-demo/generate
  2. Choose your username and a repository name (e.g., pac-demo)
  3. Click “Create repository from template”
Your repository is now created at https://github.com/yourusername/pac-demo.

​
Step 5: Install GitHub App on your repository

Next, install the GitHub Application on your repository:
1

Visit the GitHub App URL

Go to the GitHub App URL provided by tkn pac bootstrap, for example: https://github.com/apps/my-paac-application
2

Click Install

Click the “Install” button
3

Select repository

Choose the repository you just created under your username

​
Step 6: Clone your repository

Clone the repository to your local machine: 
git clone https://github.com/yourusername/pac-demo
cd pac-demo

​
Step 7: Create a Repository CRD

The Repository Custom Resource (CRD) tells Pipelines as Code which repository to watch and where to run PipelineRuns.
A Repository CR is how you configure Pipelines as Code. The namespace location where you create the CR is where your PipelineRuns will be executed.
Run the following command from inside your repository directory: 
tkn pac create repository
The CLI will detect your repository information: 
? Enter the Git repository url (default: https://github.com/yourusername/pac-demo):
Press Enter to use the default value. Next, choose the namespace where pipelines should run: 
? Please enter the namespace where the pipeline should run (default: pac-demo-pipelines):
! Namespace pac-demo-pipelines is not found
? Would you like me to create the namespace pac-demo-pipelines? (Y/n)
Press Y to create the namespace. The command will:
  • Create a Repository CR in your cluster
  • Create a .tekton directory with a pipelinerun.yaml file
  • Detect your programming language and generate an appropriate template
ℹ Directory .tekton has been created.
✓ We have detected your repository using the programming language Go.
✓ A basic template has been created in .tekton/pipelinerun.yaml, feel free to customize it.
ℹ You can test your pipeline by pushing the generated template to your git repository

​
Step 8: Create a pull request

Now let’s test Pipelines as Code by creating a pull request:
1

Create a new branch

git checkout -b tektonci
2

Commit the pipeline

git add .
git commit -m "Add Tekton CI"
3

Push the branch

git push origin tektonci
4

Create a pull request

Go to https://github.com/yourusername/pac-demo/pull/new/tektonci and create a pull request
As soon as you create the pull request, Pipelines as Code will be triggered and run on your Pull Request!

​
Step 9: View pipeline execution

You’ll see a status check on your pull request:
  • Click on the “Details” link to see the PipelineRun details
  • Pipelines as Code will provide a link to your Tekton Dashboard or OpenShift Console
  • Alternatively, use the tkn pac CLI to follow logs:
tkn pac logs -n pac-demo-pipelines -L

# Follow the latest PipelineRun logs
tkn pac logs -n pac-demo-pipelines -L

# Or select a specific PipelineRun
tkn pac logs -n pac-demo-pipelines

​
Step 10: Understanding the demo failure (optional)

If you’re using the pac-demo template, you might notice the pipeline fails on purpose. This demonstrates how Pipelines as Code:
  • Analyzes log errors from the PipelineRun
  • Matches errors to specific lines of code
  • Provides annotations on the pull request showing exactly where the issue is
To fix the error in the demo:
1

Edit main.go

Replace the contents with:
package main

import (
    "fmt"
    "os"
)

func main() {
    fmt.Fprintf(os.Stdout, "Hello world")
}
2

Commit and push

git commit -a -m "Fix linting errors"
git push origin tektonci
3

Watch the pipeline succeed

The pipeline will automatically run again and this time succeed!

​
What’s next?

Congratulations! You’ve successfully set up Pipelines as Code and run your first pipeline. Here’s what to explore next:

Core concepts

Understand the architecture and key components

Writing pipelines

Learn how to customize your pipeline definitions

Repository CRD

Configure advanced repository settings

GitOps commands

Use /test, /retest, and /cancel commands

​
Troubleshooting

​
GitHub App not receiving webhooks

If you’re using gosmee for local development, make sure it’s running: 
kubectl get pods -n pipelines-as-code | grep gosmee

​
Pipeline not triggering

Check that:
  • The Repository CR exists in your namespace: kubectl get repository -n pac-demo-pipelines
  • The GitHub App is installed on your repository
  • Your .tekton/pipelinerun.yaml has the correct annotations for the event type

​
View Pipelines as Code logs

kubectl logs -n pipelines-as-code -l app.kubernetes.io/component=controller -f

​
Next steps

Now that you have Pipelines as Code running, you can:
  • Customize your pipeline to match your project’s needs
  • Add more tasks from Tekton Hub or Artifact Hub
  • Configure advanced features like secrets, conditional execution, and path-based triggers
  • Set up additional repositories
  • Explore different Git providers like GitLab or Bitbucket

Build docs developers (and LLMs) love

Get started for freeTalk to us