Usage Guide

Pipelines-as-Code Usage Guide #

Repository CR
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 PipelineRunstatuses for that repository (5 by default). Allowing for configuration of custom parameters within the PipelineRunthat can be expanded based on certain filters.
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 (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 you repository from where the event come from, this is unless you have configured the provenance from the default branch on you Repository CR.
PipelineRun status
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
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 .
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.
Policy on actions
Policy on Pipelines-as-Code actions # Pipelines-as-Code has the concepts of Policy to let you control an action allowed to be executed by a set of users belonging to a Team on an Organisation as defined on GitHub or other Git Providers (only GitHub and Gitea is supported at the moment). List of actions supported # pull_request - This action is triggering the CI on Pipelines-as-Code, specifying a team will only allow the members of the team to trigger the CI and will not allow other members regadless if they are Owners or Collaborators of the repository or the Organization.
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. logs: show the logs of a PipelineRun form a Repository CRD.
Incoming Webhook
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.
Calendar September 13, 2023
Edit Edit this page