Pipelines-as-Code

Pipelines-as-Code is an opinionated CI/CD solution for Tekton and OpenShift Pipelines that allows you to define and manage your pipelines directly from your source code repository.

Overview

Pipelines-as-Code brings the Pipelines-as-Code methodology to Tekton. It provides a simple and declarative way to define your pipelines in your Git repository and have them automatically executed on your Kubernetes cluster. It integrates seamlessly with Git providers like GitHub, GitLab, Bitbucket, and Gitea, and provides feedback directly on your pull requests and commits.

Why Pipelines-as-Code?

Traditional CI/CD systems often require you to configure pipelines through web interfaces or separate configuration repositories. Pipelines-as-Code changes this by:

• Version Control: Your pipeline definitions live alongside your code, so they're versioned, reviewed, and evolved together
• GitOps Native: Perfect fit for GitOps workflows where everything is defined as code and managed through Git
• Developer Experience: Developers can modify pipelines using familiar Git workflows instead of learning separate CI/CD interfaces
• Review Process: Pipeline changes go through the same pull request review process as your application code
• Branch-specific Pipelines: Different branches can have different pipeline configurations for feature development
• No Vendor Lock-in: Portable Tekton-based pipelines that work across any Kubernetes cluster

How it Works

Pipelines-as-Code follows a simple event-driven workflow:

1. Git Event: A developer pushes code, opens a pull request, or creates a tag
2. Event Detection: Pipelines-as-Code receives the webhook from your Git provider (GitHub, GitLab, etc.)
3. Repository Scan: PAC looks for a .tekton/ directory in your repository
4. Pipeline Resolution: Found pipeline definitions are processed and resolved (including remote tasks from Tekton Hub)
5. Execution: PipelineRuns are created and executed on your Kubernetes cluster
6. Feedback: Results are reported back to your Git provider as status checks, PR comments, or commit statuses

The system supports advanced features like:

• Conditional execution based on file changes
• CEL expression language support for event matching
• Template variable substitution (e.g. repo URL, commit SHA, branch name)
• Secret management for secure operations
• Authorization controls to restrict pipeline execution to authorized users (repo admins, members, etc.)
• Automatic cancellation of running PipelineRuns when new events occur
• Incoming webhooks for manual pipeline triggering
• Automatic cleanup of completed PipelineRuns

Prerequisites

Before getting started with Pipelines-as-Code, ensure you have:

• Kubernetes cluster: Version 1.27+ recommended
• Tekton Pipelines: Version 0.50.0+ (latest stable recommended)
• Git Provider: One of:
  • GitHub (GitHub App or Webhook)
  • GitLab (Webhook)
  • Gitea/Forgejo (Webhook)
  • Bitbucket Cloud/Data Center (Webhook)
• CLI Tool: kubectl for cluster access
• Optional: tkn CLI for Tekton operations

Key Features

• Git-based workflow: Define your Tekton pipelines in your Git repository and have them automatically triggered on Git events like push, pull request, and comments.
• Multi-provider support: Works with GitHub (via GitHub App & Webhook), GitLab, Gitea, Bitbucket Data Center & Cloud via webhooks.
• Annotation-driven workflows: Target specific events, branches, or CEL expressions and gate untrusted PRs with /ok-to-test and OWNERS; see Running the PipelineRun.
• ChatOps style control: /test, /retest, /cancel, and branch or tag selectors let you rerun or stop PipelineRuns from PR comments or commit messages; see GitOps Commands.
• Feedback: GitHub Checks capture per-task timing, log snippets, and optional error annotations while redacting secrets; see PipelineRun status.
• Inline resolution: The resolver bundles .tekton/ resources, inlines remote tasks from Artifact Hub or Tekton Hub, and validates YAML before cluster submission; see Resolver.
• CLI: tkn pac bootstraps installs, manages Repository CRDs, inspects logs, and resolves runs locally; see the CLI guide.
• Automated housekeeping: Keep namespaces tidy with the pipelinesascode.tekton.dev/max-keep-runs annotation or global settings, and automatically cancel running PipelineRuns when new commits are pushed to the same branch; see PipelineRuns Cleanup and Cancel in progress.

Use Cases

Pipelines-as-Code is perfect for various CI/CD scenarios:

Application CI/CD

• Multi-language support: Build and test Go, Python, Node.js, Java applications
• Container workflows: Build, scan, and push container images
• Multi-environment deployments: Deploy to dev, staging, and production environments

GitOps Workflows

• Infrastructure as Code: Validate and apply Terraform, Helm charts, or Kubernetes manifests
• Configuration management: Sync application configs across environments
• Compliance checking: Run security scans and policy validation

Developer Experience

• Pull Request validation: Run comprehensive test suites on every PR
• Branch-specific builds: Different pipeline configurations for feature branches
• Dependency management: Automated security scanning and dependency updates

Advanced Scenarios

• Monorepo support: Trigger specific pipelines based on changed paths
• Integration testing: Multi-service testing with databases and external services
• Release automation: Automated tagging, changelog generation, and artifact publishing

Quick Examples

Here's a simple example of a Tekton pipeline triggered by pull requests using Pipelines as Code:

# .tekton/pull-request.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: pr-build
  annotations:
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-repository
      taskRef:
        name: git-clone
        resolver: hub
      workspaces:
      - name: output
        workspace: source
      params:
      - name: url
        value: "{{ repo_url }}"
      - name: revision
        value: "{{ revision }}"
    - name: run-tests
      runAfter: [fetch-repository]
      taskRef:
        name: golang-test
        resolver: hub
      workspaces:
      - name: source
        workspace: source
  workspaces:
  - name: source
    emptyDir: {}

Note: you can generate complete PipelineRun YAML using tkn-pac cli like below:

$ tkn pac generate
? Enter the Git event type for triggering the pipeline:  Pull Request
? Enter the target GIT branch for the Pull Request (default: main):  main
ℹ Directory .tekton has been created.
✓ A basic template has been created in .tekton/pull-request.yaml, feel free to customize it.
ℹ You can test your pipeline by pushing the generated template to your git repository

This pipeline will automatically run on every pull request to the main branch, fetch the code, and run tests.

More Examples

Python Application with Testing:

# .tekton/python-ci.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: python-ci
  annotations:
    pipelinesascode.tekton.dev/on-event: "[pull_request, push]"
    pipelinesascode.tekton.dev/on-target-branch: "[main, develop]"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-source
      taskRef:
        name: git-clone
        resolver: hub
      workspaces:
      - name: output
        workspace: source
      params:
      - name: url
        value: "{{ repo_url }}"
      - name: revision
        value: "{{ revision }}"
    - name: python-test
      runAfter: [fetch-source]
      taskRef:
        name: python-test
        resolver: hub
      workspaces:
      - name: source
        workspace: source
      params:
      - name: requirements_file
        value: "requirements.txt"
      - name: python_version
        value: "3.11"
  workspaces:
  - name: source
    emptyDir: {}

Container Build and Push:

# .tekton/build-push.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: build-push
  annotations:
    pipelinesascode.tekton.dev/on-event: "[push]"
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-source
      taskRef:
        name: git-clone
        resolver: hub
      workspaces:
      - name: output
        workspace: source
      params:
      - name: url
        value: "{{ repo_url }}"
      - name: revision
        value: "{{ revision }}"
    - name: build-push
      runAfter: [fetch-source]
      taskRef:
        name: buildah
        resolver: hub
      workspaces:
      - name: source
        workspace: source
      params:
      - name: IMAGE
        value: "quay.io/myorg/myapp:{{ revision }}"
      - name: DOCKERFILE
        value: "./Dockerfile"
  workspaces:
  - name: source
    emptyDir: {}

Conditional Execution Based on File Changes:

# .tekton/docs-only.yaml
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
  name: docs-validation
  annotations:
    pipelinesascode.tekton.dev/on-event: "[pull_request]"
    pipelinesascode.tekton.dev/on-target-branch: "[main]"
    pipelinesascode.tekton.dev/on-path-changed: "[docs/**, **.md]"
spec:
  pipelineSpec:
    tasks:
    - name: fetch-source
      taskRef:
        name: git-clone
        resolver: hub
      workspaces:
      - name: output
        workspace: source
      params:
      - name: url
        value: "{{ repo_url }}"
      - name: revision
        value: "{{ revision }}"
    - name: lint-docs
      runAfter: [fetch-source]
      taskRef:
        name: markdown-lint
        resolver: hub
      workspaces:
      - name: source
        workspace: source
  workspaces:
  - name: source
    emptyDir: {}

Getting Started

5-Minute Quickstart

Get up and running with Pipelines-as-Code in just a few minutes:

1. Install the CLI:

   brew install openshift-pipelines/pipelines-as-code/tkn-pac

2. Bootstrap a new repository (if you have a GitHub repo):

   $ tkn pac bootstrap github
   ? Enter the Git repository url (default: https://github.com/owner/repo):
   ? Please enter your GitHub access token: ****
   ✓ Repository owner/repo has been created
   ✓ Repository has been configured

3. Generate your first pipeline:

   $ cd your-repo
   $ tkn pac generate
   ? Enter the Git event type for triggering the pipeline: Pull Request
   ? Enter the target GIT branch for the Pull Request (default: main): main
   ✓ A basic template has been created in .tekton/pull-request.yaml

4. Commit and push:

   git add .tekton/
   git commit -m "Add Pipelines-as-Code configuration"
   git push

5. Create a pull request and watch your pipeline run automatically! 🎉

Verification: Check your repository's "Actions" or "Checks" tab to see the pipeline execution.

Installation

Option 1: Homebrew (macOS/Linux)

brew install openshift-pipelines/pipelines-as-code/tkn-pac

Option 2: Direct Download

# Download latest release
curl -L https://github.com/openshift-pipelines/pipelines-as-code/releases/latest/download/tkn-pac-linux-amd64 -o tkn-pac
chmod +x tkn-pac
sudo mv tkn-pac /usr/local/bin/

Option 3: Install on Kubernetes Cluster

# Install Pipelines-as-Code controller
kubectl apply -f https://github.com/openshift-pipelines/pipelines-as-code/releases/latest/download/release.yaml

Verify Installation:

$ tkn pac version
Pipelines-as-Code version: v0.x.x

For detailed installation instructions including Windows, see the official documentation.

Creating your first repository

Once you have the tkn-pac CLI installed, you can set up your first repository with the bootstrap command. We have a full walk-through tutorial here:

https://pipelinesascode.com/docs/install/getting-started/

Documentation

For more detailed information, please refer to the official documentation.

The documentation for the development branch is available here.

Contributing

We welcome contributions from everyone! Whether you're fixing bugs, adding features, improving documentation, or helping other users, your contributions make Pipelines-as-Code better.

Getting Started

• Read our development guide for setup instructions
• Check out good first issues to get started
• Review our Code of Conduct to understand our community standards

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Run make test and make lint to verify your changes
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Contribution Types

• Code: Bug fixes, new features, performance improvements
• Documentation: User guides, API docs, examples, blog posts
• Testing: Writing tests, improving test coverage, reporting bugs
• Community: Answering questions, mentoring new contributors, organizing events

Community

Join our vibrant community of developers and DevOps engineers:

Getting Help

• GitHub Discussions: Ask questions and get community support in GitHub Discussions
• Slack: Join us on the TektonCD Slack in the #pipelinesascode channel (Join TektonCD Slack)
• Issues: Report bugs and request features via GitHub Issues

Contributing

• Good First Issues: Start contributing with good first issues
• Help Wanted: Check out help wanted issues
• Developer Docs: See our development guide

Stay Updated

• Releases: Follow our releases for the latest updates
• Blog: Read about new features and use cases on the OpenShift Pipelines website.

License

This project is licensed under the Apache 2.0 License.