Usage Guide on Pipelines as Code

Repository CR

Mon, 01 Jan 0001 00:00:00 +0000

Repository CR #

The Repository CR serves the following purposes:

Informing Pipelines-as-Code that an event from a specific URL needs to be handled.
Specifying the namespace where the PipelineRuns will be executed.
Referencing an API secret, username, or API URL if necessary for Git provider platforms that require it (e.g., when using webhooks instead of the GitHub application).
Providing the last PipelineRun statuses for the repository (5 by default).
Letting you declare custom parameters within the PipelineRun that can be expanded based on certain filters.

To configure Pipelines-as-Code, a Repository CR must be created within the user’s namespace, for example project-repository, where their CI will run.

Resolver

Mon, 01 Jan 0001 00:00:00 +0000

Pipelines-as-Code resolver #

The Pipelines-as-Code resolver ensures that the PipelineRun you are running doesn’t conflict with others.

Pipelines-as-Code parses any files ending with a .yaml or .yml suffix in the .tekton directory and subdirectory at the root of your repository. It will automatically attempt to detect any Tekton resources like Pipeline, PipelineRun, Task.

When detecting a PipelineRun it will try to resolve it as a single PipelineRun with an embedded PipelineSpec of the referenced Task or Pipeline. This embedding ensures that all dependencies required for execution are contained within a single PipelineRun at the time of execution on the cluster.

Authoring PipelineRun

Mon, 01 Jan 0001 00:00:00 +0000

Authoring PipelineRuns in `.tekton/` directory #

Pipelines-as-Code will always try to be as close to the Tekton template as possible. Usually, you will write your template and save them with a .yaml extension, and Pipelines-as-Code will run them.
The .tekton directory must be at the top level of the repo. You can reference YAML files in other repos using remote URLs (see Remote HTTP URLs for more information), but PipelineRuns will only be triggered by events in the repository containing the .tekton directory.

Matching a PipelineRun

Mon, 01 Jan 0001 00:00:00 +0000

Matching a PipelineRun to a Git provider Event #

A PipelineRun can be matched to a Git provider event by using specific annotations in the PipelineRun metadata.

For example, when you have these as metadata in your PipelineRun:

metadata:
  name: pipeline-pr-main
annotations:
  pipelinesascode.tekton.dev/on-target-branch: "[main]"
  pipelinesascode.tekton.dev/on-event: "[pull_request]"

Pipelines-as-Code will match the PipelineRun pipeline-pr-main if the Git provider events target the branch main and it’s coming from a [pull_request]

Multiple target branches can be specified, separated by commas, e.g.:

Running the PipelineRun

Mon, 01 Jan 0001 00:00:00 +0000

Running the PipelineRun #

Pipelines-as-Code (PAC) can be used to run pipelines on events such as pushes or pull requests. When an event occurs, PAC will try to match it to any PipelineRuns located in the .tekton directory of your repository that are annotated with the appropriate event type.

The PipelineRuns definitions are fetched from the .tekton directory at the root of your repository from where the event comes from, this is unless you have configured the provenance from the default branch on your Repository CR.

For example, if a PipelineRun has this annotation:

GitOps Commands

Mon, 01 Jan 0001 00:00:00 +0000

GitOps Commands #

Pipelines-as-Code supports the concept of GitOps commands, which allow users to issue special commands in a comment on a Pull Request or a pushed commit to control Pipelines-as-Code.

The advantage of using a GitOps command is that it provides a journal of all the executions of your pipeline directly on your Pull Request, near your code.

GitOps Commands on Pull Requests #

For example, when you are on a Pull Request, you may want to restart all your PipelineRuns. To do so, you can add a comment on your Pull Request starting with /retest, and all PipelineRuns attached to that Pull Request will be restarted.

PipelineRun status

Mon, 01 Jan 0001 00:00:00 +0000

Status #

GitHub apps #

After the PipelineRun has finished, its status will be shown in the GitHub Check tabs, along with a concise overview of the status the name and the duration of each task in the pipeline. If the task has a displayName it will use it as the description of the task or otherwise just the task name.

If any step fails, a small portion of the log from that step will also be included in the output.

Private Repositories

Mon, 01 Jan 0001 00:00:00 +0000

Private repositories #

Pipelines-as-Code allows the use of private repositories by creating or updating a secret in the target namespace. This secret contains the user token required for the git-clone task to clone private repositories.

Whenever Pipelines-as-Code creates a new PipelineRun in the target namespace, it also creates a secret with a specific name format:

pac-gitauth-REPOSITORY_OWNER-REPOSITORY_NAME-RANDOM_STRING

This secret contains a Git Config file named .gitconfig and a Git credentials file named .git-credentials. These files configure the base HTTPS URL of the git provider (such as https://github.com) using the token obtained from the GitHub application or from a secret attached to the repository CR on git provider when using the webhook method.

PipelineRuns Cleanup

Mon, 01 Jan 0001 00:00:00 +0000

PipelineRuns Cleanups #

There can be many PipelineRuns into a user namespace and Pipelines-as-Code has the ability to only keep a certain amount of PipelineRuns and cleaning the old ones.

When your PipelineRun has this annotation :

pipelinesascode.tekton.dev/max-keep-runs: "maxNumber"

Pipelines-as-Code sees this and will start cleaning up right after one of the PipelineRun finishes to a successful execution keeping only the last maxNumber of PipelineRuns.

It will skip the Running or Pending PipelineRuns but will not skip the PipelineRuns with Unknown status.

Custom Parameters

Mon, 01 Jan 0001 00:00:00 +0000

Custom Parameters #

Using the {{ param }} syntax, Pipelines-as-Code lets you expand a variable or the payload body inside a template within your PipelineRun.

By default, several variables are exposed according to the event. To view all the variables exposed by default, refer to the documentation on Authoring PipelineRuns.

With the custom parameter, you can specify some custom values to be replaced inside the template.

Utilizing the Tekton PipelineRun parameters feature may generally be the preferable approach, and custom params expansion should only be used in specific scenarios where Tekton params cannot be used.

As an example, here is a custom variable in the Repository CR spec:

Incoming Webhook

Mon, 01 Jan 0001 00:00:00 +0000

Incoming webhook #

Pipelines-as-Code support the concept of incoming webhook URL. It let you trigger PipelineRun in a Repository using a shared secret and URL, instead of creating a new code iteration.

Incoming Webhook URL #

To use incoming webhooks in Pipelines-as-Code, you must configure the incoming field in your Repository CRD. This field references a Secret, which serves as the shared secret, as well as the branches targeted by the incoming webhook. Once configured, Pipelines-as-Code will match PipelineRuns located in your .tekton directory if the on-event annotation of the targeted pipelinerun is targeting a push or incoming event.

Policy on actions

Mon, 01 Jan 0001 00:00:00 +0000

Policy on Pipelines-as-Code Actions #

Pipelines-as-Code uses policies to control which actions can be performed by users who belong to specific teams within an organization, as defined on GitHub or other supported Git providers (currently GitHub and Gitea).

This feature is supported on the following providers

Git Provider Supported

GitHub App ✅️

GitHub Webhook ✅️

Gitea ✅️

GitLab ❌️

Bitbucket Cloud ❌️

Bitbucket Data Center ❌️

Git Provider	Supported
GitHub App	✅️
GitHub Webhook	✅️
Gitea	✅️
GitLab	❌️
Bitbucket Cloud	❌️
Bitbucket Data Center	❌️

Supported Actions #

pull_request - This action triggers the CI in Pipelines-as-Code. Specifying a team restricts the ability to trigger CI to members of that team, regardless of whether they are repository or organization owners or collaborators. However, members listed in the OWNERS file are still permitted to trigger the CI.

CLI tkn-pac

Mon, 01 Jan 0001 00:00:00 +0000

Pipelines-as-Code CLI #

Pipelines-as-Code provides a powerful CLI designed to work as a plug-in to the Tekton CLI (tkn).

tkn pac allows you to:

bootstrap: quickly bootstrap a Pipelines-as-Code installation.
create: create a new Pipelines-as-Code Repository definition.
delete: delete an existing Pipelines-as-Code Repository definition.
generate: generate a simple pipelinerun to get you started with Pipelines-as-Code.
list: list Pipelines-as-Code Repositories.
logs: show the logs of a PipelineRun from a Repository CRD.
describe: describe a Pipelines-as-Code Repository and the runs associated with it.
resolve: Resolve a pipelinerun as if it were executed by pipelines as code on service.
webhook: Updates webhook secret.
info: Show information (currently only about your installation with info install).

Install #

Binary

You can grab the latest binary directly for your operating system from the releases page.

OpenAPI Schema Validation

Mon, 01 Jan 0001 00:00:00 +0000

OpenAPI Schema Validation for Repository CRDs #

Pipelines-as-Code provides OpenAPI schema validation for its Custom Resource Definitions (CRDs), which helps in writing the Repository resources. This page explains what OpenAPI schemas are, their benefits, and how to leverage them in your development environment.

What is OpenAPI Schema Validation? #

OpenAPI schema validation is a mechanism that adds metadata to Kubernetes CRDs, providing:

Type information: Specifies expected data types for fields
Required fields: Marks which fields must be present
Pattern validation: Enforces specific formats (e.g., URLs must start with http:// or https://)
Enumeration validation: Limits fields to a predefined set of values
Field descriptions: Documents the purpose of each field

When you create or modify a Repository resource, the OpenAPI schema helps validate your configuration before it’s applied to the cluster, catching errors early in the development process.

Usage Guide on Pipelines as Code

Repository CR

Repository CR #

Resolver

Pipelines-as-Code resolver #

Authoring PipelineRun

Authoring PipelineRuns in .tekton/ directory #

Matching a PipelineRun

Matching a PipelineRun to a Git provider Event #

Running the PipelineRun

Running the PipelineRun #

GitOps Commands

GitOps Commands #

GitOps Commands on Pull Requests #

PipelineRun status

Status #

GitHub apps #

Private Repositories

Private repositories #

PipelineRuns Cleanup

PipelineRuns Cleanups #

Custom Parameters

Custom Parameters #

Incoming Webhook

Incoming webhook #

Incoming Webhook URL #

Policy on actions

Policy on Pipelines-as-Code Actions #

Supported Actions #

CLI tkn-pac

Pipelines-as-Code CLI #

Install #

OpenAPI Schema Validation

OpenAPI Schema Validation for Repository CRDs #

What is OpenAPI Schema Validation? #

Authoring PipelineRuns in `.tekton/` directory #