OpenShift/Tekton Pipelines As Code “v2”

Shivam Mukhade
7 min readJul 29, 2022

This article will introduce the redesigned version of PipelinesAsCode and how you can run your CI the GitOps way with OpenShift Pipelines/Tekton Pipelines.

> NOTE: This is an updated version of a previous article https://towardsdev.com/openshift-pipelines-as-code-a3751c300f0a which featured v0.5.3. After v0.5.x there has been a redesigned, at present the latest version is v0.11.0 which has all the old features with a lot of new features 😃.

# What is Pipelines as Code (PAC)?

An opinionated CI based on OpenShift Pipelines / Tekton.
PipelinesAsCode is a CI system that you can integrate with your git provider and a Kubernetes Cluster, it would run your CI Tekton Pipelines on the cluster and report status back to your repository, which means once you integrate you would have everything on your git.

If you are new to Tekton/OpenShift Pipelines, you can check out https://sm43.medium.com/world-of-tekton-part-1-999738d63e25

Pipelines As Code is compatible with OpenShift Clusters as well as any Kubernetes Cluster.

You can find pipelines as code documentation at https://pipelinesascode.com 😺

# Features

  • Pull-request status support: When iterating over a Pull Request, status and control are done on the platform.
  • GitHub Checks API support to set the status of a PipelineRun including rechecks
  • GitHub Pull Request and Commit event support
  • Pull-request actions in comments such as /retest or /test
  • Git events filtering and support for separate pipelines for each event
  • Automatic Task resolution in Pipelines (local Tasks, Tekton Hub, and remote URLs)
  • Efficient use of GitHub blobs and objects API for retrieving configuration
  • ACL over a GitHub organization or with a Prow-style OWNER file.
  • tkn-pac plug-in for Tekton CLI for managing pipelines-as-code repositories and bootstrapping.
  • Gitlab, Bitbucket Server, Bitbucket Cloud, and GitHub through Webhook support.
  • Concurrency

# Installation

Before Installing PAC, we need to install Tekton Pipelines /OpenShift Pipelines.

If you are on OpenShift Cluster, you can install the OpenShift Pipelines Operator from the Operator Hub. Make sure you disable the PAC installed with the Operator through TektonConfig CR to install the latest PAC.

Alternatively, you can install Tekton Pipelines on your Kubernetes Cluster. You can find the installation steps here.

Make sure Pipelines version ≥ v0.25.0

Now, you can install Pipelines As Code using the release YAML published on the release page.

For OpenShift,

kubectl apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/release-v0.11.x/release.yaml

For Kubernetes,

kubectl apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/release-v0.11.x/release.k8s.yaml

If you are an OpenShift user, you can get Pipelines As Code with the OpenShift Pipelines Operator version, below is the version matrix

OpenShift Pipelines Operator: Pipelines As Code
v1.7.x : v0.5.x (TP)
v1.8.x : v0.10.x (TP)
v1.9.x v0.11.x (GA) (to be released)

You can also download the tkn-pac binary which is a CLI extension to tkn CLI from the release page.

CLI will help you to install Pipelines As Code as well as integrate with your git project.

Let’s try it out!

  • I am going to use an OpenShift Cluster v4.11, but you can use any Kubernetes cluster
    If you are using a K8s cluster, you need to expose the Pipelines As Code controller to use with the git provider.
  • I am going to use a GitHub Repository for the demo.

There are 2 ways to integrate with GitHub Repository

  • GitHub App (Recommended)
  • GitHub Webhook

For other Git providers GitLab, Bitbucket Cloud/Server, only Webhook way supported.

I am going to install using tkn-pac CLI and create a GitHub App.

This command did the following:
- installed Pipelines As Code, then
- created GitHub App
- installed the GitHub App on our Repository which we want to use with PAC

The next step would be to register the repository on the cluster, we are going to use CLI for this.

Run this command inside your locally cloned repository, CLI will pick up default values.

This command registered your git repo on the cluster by creating a Repository CR. Also, it created a sample PipelineRun template in .tekton directory which you can modify according to your project.

Let’s see the PipelineRun…

---
apiVersion: tekton.dev/v1beta1
kind: PipelineRun
metadata:
name: pac-app
annotations:
# The event we are targeting as seen from the webhook payload
# this can be an array too, i.e: [pull_request, push]
pipelinesascode.tekton.dev/on-event: "[pull_request, push]"
# The branch or tag we are targeting (ie: main, refs/tags/*)
pipelinesascode.tekton.dev/on-target-branch: "main"

# Fetch the git-clone task from hub, we are able to reference later on it
# with taskRef and it will automatically be embedded into our pipeline.
pipelinesascode.tekton.dev/task: "git-clone"
# You can add more tasks in here to reuse, browse the one you like from here
# https://hub.tekton.dev/
# example:
# pipelinesascode.tekton.dev/task-2: "[maven, buildah]"

# How many runs we want to keep attached to this event
pipelinesascode.tekton.dev/max-keep-runs: "5"
spec:
params:
# The variable with brackets are special to Pipelines as Code
# They will automatically be expanded with the events from Github.
- name: repo_url
value: "{{ repo_url }}"
- name: revision
value: "{{ revision }}"
pipelineSpec:
params:
- name: repo_url
- name: revision
workspaces:
- name: source
- name: basic-auth
tasks:
- name: fetch-repository
taskRef:
name: git-clone
workspaces:
- name: output
workspace: source
- name: basic-auth
workspace: basic-auth
params:
- name: url
value: $(params.repo_url)
- name: revision
value: $(params.revision)

# Customize this task if you like, or just do a taskRef
# to one of the hub task.
- name: noop-task
runAfter:
- fetch-repository
workspaces:
- name: source
workspace: source
taskSpec:
workspaces:
- name: source
steps:
- name: noop-task
image: registry.access.redhat.com/ubi8/ubi-micro:8.4
workingDir: $(workspaces.source.path)
script: |
exit 0
workspaces:
- name: source
volumeClaimTemplate:
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 1Gi
# This workspace will inject secret to help the git-clone task to be able to
# checkout the private repositories
- name: basic-auth
secret:
secretName: "{{ git_auth_secret }}"

You can update the PipelineRun with the Tasks required according to your project.

If we see the annotations those are Pipelines As Code specific

  • pipelinesascode.tekton.dev/on-event : this defines on which event your Pipeline should run, after creating a pull request or pushing a commit to your branch or both
  • pipelinesascode.tekton.dev/on-target-branch: this defines the branch on which when a commit is pushed or pull request is created, the Pipeline will be run.
  • pipelinesascode.tekton.dev/task: If you would like to use Tasks from Tekton Hub, then you can add an annotation with its name and reference it in your PipelineRun, PAC will fetch it for you and resolve it in the PipelineRun.
    You can also keep Tasks in .tekton directory and PAC will resolve it from there.
  • pipelinesascode.tekton.dev/cel-expression: You can have more control over when to run your PipelineRun.
    pipelinesascode.tekton.dev/on-cel-expression: |
    event == "pull_request" && target_branch == "main" && source_branch == "wip"
  • If your repository is private, for cloning the repository PAC will create a temporary secret and use it in the PipelineRun. You just need to use "{{ git_auth_secret }}" for the secretName.

You can find more details on how to write and use PAC features at https://pipelinesascode.com/docs/guide/authoringprs.

To see PAC in action, we can just commit the template provided by PAC CLI in a new branch and create a Pull Request against main branch.

Once PipelineRun is completed, you will get the status below

If there are any changes needed in your code or PipelineRun, then you can do the changes and push a new commit and PAC will fetch the latest and run the PipelineRun.

To retrigger the CI, you can comment /retest or /teston your Pull Request.

You can have multiple PipelineRun in .tekton directory, then for each Pipeline there would be one check run in status as below

# Concurrency

You can configure concurrency in Repository CR on the cluster. In v0.11.x, only basis concurrency is supported where you can define a limit defining at any moment how many PipleineRun should be running.

So, if you have 4 PipelineRuns in .tekton directory and the concurrency limit is 1 then only one will run at a time, and the rest will be queued. The order of execution is random at present.

In the future, we will be adding more features having more control over the order of execution.

Example:

apiVersion: pipelinesascode.tekton.dev/v1alpha1
kind: Repository
metadata:
name: sm43-pac-app
spec:
url: https://github.com/sm43/pac-app
concurrency_limit: 1

# Status

PAC adds the last 5 PipelineRuns in the status of Repository CR too.

for example:

pipelinerun_status:
- completionTime: "2022-07-29T06:46:08Z"
conditions:
- lastTransitionTime: "2022-07-29T06:46:08Z"
message: 'Tasks Completed: 2 (Failed: 0, Cancelled 0), Skipped: 0'
reason: Succeeded
status: "True"
type: Succeeded
event_type: pull_request
logurl: https://console-openshift-console.apps.shivam.devcluster.openshift.com/k8s/ns/pac-app-pipelines/tekton.dev~v1beta1~PipelineRun/pac-app-c492v
pipelineRunName: pac-app-c492v
sha: 1d7d858b4792bb0f01da51094058023ba6978fcc
sha_url: https://github.com/sm43/pac-app/commit/1d7d858b4792bb0f01da51094058023ba6978fcc
startTime: "2022-07-29T06:45:26Z"
target_branch: main
title: Adds Pipelinerun template

If you don’t have access to setting up GitHub App then you can set up GitHub Webhook, or if you want to use PAC on Bitbucket or GitLab.

# Setup Webhook

To set up a webhook, you need to first install PipelineAsCode, you can use release YAML for it.

Next, you can use tkn pac setup command to set up and then run tkn pac create repo command to register.

To know more about how to set up a webhook, follow the docs at https://pipelinesascode.com.

End…

That’s all from this article… There are many more features coming soon. If you have any questions or feature requests, feel free to create an issue at https://github.com/openshift-pipelines/pipelines-as-code/issues/new.

Do leave your feedback or if you want to know more, you can reach me on GitHub or LinkedIn.

--

--

Shivam Mukhade

Open-Source | Software Engineer | Kubernetes | OpenShift | Tekton | PipelinesAsCode