Usage Guide

Pipelines as Code Usage Guide #

Repository CRD
Repository CRD # The purposes of the Repository CRD is: To let Pipelines as Code know that this event from this URL needs to be handled. To let Pipelines as Code know on which namespace the PipelineRuns are going to be executed. To reference an api secret, username or api URL if needed for the Git provider platforms that requires it (ie: when you are using webhooks method and not the GitHub application).
Pipelines as Code resolver # Pipelines as Code resolver ensures the PipelineRun you are running does not conflicts with others. If Pipelines as Code sees a PipelineRun with a reference to a Task or to a Pipeline in any YAML file located in the .tekton/ directory it will automatically try to resolves it (see below) as a single PipelineRun with an embedded PipelineSpec to a PipelineRun. The resolver will then transform the Pipeline Name field to a GenerateName based on the Pipeline name as well.
Authoring PipelineRun
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 .
Running the PipelineRun
Running the PipelineRun # Pipelines as Code will run any PipelineRuns committed to the default branch of the repo when the specified events occur on the repo. For example, if a PipelineRun on the default branch has the annotation "[pull_request]", it will run whenever a pull request event occurs. Pipelines as Code will also run any PipelineRuns from a branch in a pull request (or merge request in Gitlab).
PipelineRun status
Status # GitHub apps # When the pipeline finishes, the status will be added in the GitHub Check tabs with a short recap of how long each task of your pipeline took and the output of tkn pr describe. Log error snippet # When we detect an error in one of the task of the Pipeline we will show a small snippet of the last 3 lines in the task breakdown.
Private Repositories
Private repositories # Pipelines as Code support private repositories by creating or updating a secret in the target namespace with the user token for the git-clone task to use and be able to clone private repositories. Whenever Pipelines as Code create a new PipelineRun in the target namespace it will create or update a secret called: pac-gitauth-REPOSITORY_OWNER-REPOSITORY_NAME-RANDOM_STRING The secret contains a .gitconfig and Git credentials .git-credentials with the https URL using the token it discovered from the GitHub application or attached to the secret.
PipelineRuns Cleanup
PipelineRuns Cleanups # There can be many PipelineRuns into a user namespace and Pipelines as Code has the ability to only keep several PipelineRuns that matches an event. For example if the PipelineRun has this annotation : "maxNumber" Pipelines as Code sees this and will start cleaning up right after it finishes a successful execution keeping only the maxNumber of PipelineRuns. It will skip the Running PipelineRuns but will not skip the PipelineRuns with Unknown status.
CLI tkn-pac
Pipelines as Code CLI # Pipelines as Code provide 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.
Incoming Webhook
Incoming webhook # Pipelines as Code support the concept of incoming webhook URL. Which let you start a PipelineRun in a Repository by a URL and a shared secret rather than having to generate a new code iteration. Incoming Webhook URL # You need to set your incoming match your Repository CRD, in your match you specify a reference Secret which will be used as a shared secret and the branches targetted by the incoming webhook.