Repository files navigation

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.

Pipelines-as-Code brings thePipelines-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.

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

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

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

• 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 andOWNERS; seeRunning 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; seeGitOps Commands.
• Feedback: GitHub Checks capture per-task timing, log snippets, and optional error annotations while redacting secrets; seePipelineRun status.
• Inline resolution: The resolver bundles.tekton/ resources, inlines remote tasks from Artifact Hub or Tekton Hub, and validates YAML before cluster submission; seeResolver.
• CLI:tkn pac bootstraps installs, manages Repository CRDs, inspects logs, and resolves runs locally; see theCLI guide.
• Automated housekeeping: Keep namespaces tidy with thepipelinesascode.tekton.dev/max-keep-runs annotation or global settings, and automatically cancel running PipelineRuns when new commits are pushed to the same branch; seePipelineRuns Cleanup andCancel in progress.

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

• 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

• 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

• 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

• 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

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

# .tekton/pull-request.yamlapiVersion:tekton.dev/v1beta1kind:PipelineRunmetadata:name:pr-buildannotations:pipelinesascode.tekton.dev/on-event:"[pull_request]"pipelinesascode.tekton.dev/on-target-branch:"[main]"spec:pipelineSpec:tasks:    -name:fetch-repositorytaskRef:name:git-cloneresolver:hubworkspaces:      -name:outputworkspace:sourceparams:      -name:urlvalue:"{{ repo_url }}"      -name:revisionvalue:"{{ revision }}"    -name:run-testsrunAfter:[fetch-repository]taskRef:name:golang-testresolver:hubworkspaces:      -name:sourceworkspace:sourceworkspaces:  -name:sourceemptyDir:{}

Note: you can generate complete PipelineRun YAML usingtkn-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 themain branch, fetch the code, and run tests.

Python Application with Testing:

# .tekton/python-ci.yamlapiVersion:tekton.dev/v1beta1kind:PipelineRunmetadata:name:python-ciannotations:pipelinesascode.tekton.dev/on-event:"[pull_request, push]"pipelinesascode.tekton.dev/on-target-branch:"[main, develop]"spec:pipelineSpec:tasks:    -name:fetch-sourcetaskRef:name:git-cloneresolver:hubworkspaces:      -name:outputworkspace:sourceparams:      -name:urlvalue:"{{ repo_url }}"      -name:revisionvalue:"{{ revision }}"    -name:python-testrunAfter:[fetch-source]taskRef:name:python-testresolver:hubworkspaces:      -name:sourceworkspace:sourceparams:      -name:requirements_filevalue:"requirements.txt"      -name:python_versionvalue:"3.11"workspaces:  -name:sourceemptyDir:{}

Container Build and Push:

# .tekton/build-push.yamlapiVersion:tekton.dev/v1beta1kind:PipelineRunmetadata:name:build-pushannotations:pipelinesascode.tekton.dev/on-event:"[push]"pipelinesascode.tekton.dev/on-target-branch:"[main]"spec:pipelineSpec:tasks:    -name:fetch-sourcetaskRef:name:git-cloneresolver:hubworkspaces:      -name:outputworkspace:sourceparams:      -name:urlvalue:"{{ repo_url }}"      -name:revisionvalue:"{{ revision }}"    -name:build-pushrunAfter:[fetch-source]taskRef:name:buildahresolver:hubworkspaces:      -name:sourceworkspace:sourceparams:      -name:IMAGEvalue:"quay.io/myorg/myapp:{{ revision }}"      -name:DOCKERFILEvalue:"./Dockerfile"workspaces:  -name:sourceemptyDir:{}

Conditional Execution Based on File Changes:

# .tekton/docs-only.yamlapiVersion:tekton.dev/v1beta1kind:PipelineRunmetadata:name:docs-validationannotations: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-sourcetaskRef:name:git-cloneresolver:hubworkspaces:      -name:outputworkspace:sourceparams:      -name:urlvalue:"{{ repo_url }}"      -name:revisionvalue:"{{ revision }}"    -name:lint-docsrunAfter:[fetch-source]taskRef:name:markdown-lintresolver:hubworkspaces:      -name:sourceworkspace:sourceworkspaces:  -name:sourceemptyDir:{}

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.

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

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

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

Verify Installation:

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

For detailed installation instructions including Windows, see theofficial documentation.

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

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

For more detailed information, please refer to theofficial documentation.

The documentation for the development branch is availablehere.

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.

• Read ourdevelopment guide for setup instructions
• Check outgood first issues to get started
• Review ourCode of Conduct to understand our community standards

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes and add tests
4. Runmake test andmake 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

• 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

Join our vibrant community of developers and DevOps engineers:

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

• Good First Issues: Start contributing withgood first issues
• Help Wanted: Check outhelp wanted issues
• Developer Docs: See ourdevelopment guide

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

This project is licensed under theApache 2.0 License.