OpenShift docs are moving and will soon only be available at docs.redhat.com, the home of all Red Hat product documentation. Explore the new docs experience today.
  1. Documentation
    2. history
×

Using Pipelines as Code

Pipelines as Code is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

With Pipelines as Code, cluster administrators and users with the required privileges can define pipeline templates as part of source code Git repositories. When triggered by a source code push or a pull request for the configured Git repository, the feature runs the pipeline and reports the status.

Key features

Pipelines as Code supports the following features:

  • Pull request status and control on the platform hosting the Git repository.

  • GitHub Checks API to set the status of a pipeline run, including rechecks.

  • GitHub pull request and commit events.

  • Pull request actions in comments, such as /retest.

  • Git events filtering and a separate pipeline for each event.

  • Automatic task resolution in Pipelines, including local tasks, Tekton Hub, and remote URLs.

  • Retrieval of configurations using GitHub blobs and objects API.

  • Access Control List (ACL) over a GitHub organization, or using a Prow style OWNER file.

  • The tkn-pac CLI plugin for managing bootstrapping and Pipelines as Code repositories.

  • Support for GitHub App, GitHub Webhook, Bitbucket Server, and Bitbucket Cloud.

Installing Pipelines as Code on an OpenShift Container Platform

Pipelines as Code is installed by default when you install the Red Hat OpenShift Pipelines Operator. If you are using Pipelines 1.7 or later versions, skip the procedure for manual installation of Pipelines as Code.

However, if you want to disable the default installation of Pipelines as Code with the Red Hat OpenShift Pipelines Operator, set the value of the enablePipelinesAsCode field as false in the TektonConfig custom resource.

...
spec:
    addon:
      enablePipelinesAsCode: false
...

To install Pipelines as Code using the Operator, set the value of the enablePipelinesAsCode field to true.

Procedure

  1. To manually install Pipelines as Code on a OpenShift Container Platform cluster instead of the default installation with the Red Hat OpenShift Pipelines Operator, run the following command:

    $ VERSION=0.5.4
$ oc apply -f https://raw.githubusercontent.com/openshift-pipelines/pipelines-as-code/release-$VERSION/release-$VERSION.yaml

    For the latest stable version, check the release page. In addition, check the Red Hat OpenShift Pipelines release notes to ensure that the Pipelines as Code version is compatible with the Red Hat OpenShift Pipelines version.

    This command installs Pipelines as Code in the pipelines-as-code namespace and creates user roles and the route URL for the Pipelines as Code event listener.

  2. Note the route URL for the Pipelines as Code controller created on the cluster:

    $ echo https://$(oc get route -n pipelines-as-code el-pipelines-as-code-interceptor -o jsonpath='{.spec.host}')

    This URL will be needed later when you configure the Git repository hosting service provider.

  3. (Optional) To allow non-administrative users to create repository custom resource definitions (CRDs) in their respective namespaces, create a RoleBinding object with the name openshift-pipeline-as-code-clusterrole in the namespace. For example, to allow a user to create a repository CRD in the user-ci namespace, run the following command:

    $ oc adm policy add-role-to-user openshift-pipeline-as-code-clusterrole user -n user-ci

    Alternatively, apply the following YAML file using the oc apply -f <RoleBinding.yaml> command:

    apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: openshift-pipeline-as-code-clusterrole
  namespace: user-ci
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: openshift-pipeline-as-code-clusterrole
subjects:
- apiGroup: rbac.authorization.k8s.io
  kind: User
  name: user

Installing Pipelines as Code CLI

Cluster administrators can use the tkn-pac CLI tool on local machines or as containers for testing. The tkn-pac CLI tool is installed automatically when you install the tkn CLI for Red Hat OpenShift Pipelines.

You can also install the tkn-pac tkn-pac version 0.23.1 binaries for the supported platforms:

Configuring Pipelines as Code for a Git repository hosting service provider

After installing Pipelines as Code, cluster administrators can configure a Git repository hosting service provider. Currently, the following services are supported:

  • Github App

  • Github Webhook

  • Bitbucket Server

  • Bitbucket Cloud

GitHub App is the recommended service for using Pipelines as Code.

Configuring Pipelines as Code for a GitHub App

GitHub Apps act as a point of integration with Red Hat OpenShift Pipelines and bring the advantage of Git-based workflows to OpenShift Pipelines. Cluster administrators can configure a single GitHub App for all cluster users. For GitHub Apps to work with Pipelines as Code, ensure that the webhook of the GitHub App points to the Pipelines as Code event listener route (or ingress endpoint) that listens for GitHub events.

Configuring a GitHub App

Cluster administrators can create a GitHub App by running the following command:

$ tkn pac bootstrap github-app

If the tkn pac CLI plugin is not installed, you can create the GitHub App manually.

Procedure

To create and configure a GitHub App manually for Pipelines as Code, perform the following steps:

  1. Sign in to your GitHub account.

  2. Go to Settings -→ Developer settings -→ GitHub Apps, and click New GitHub App.

  3. Provide the following information in the GitHub App form:

    • GitHub Application Name: OpenShift Pipelines

    • Homepage URL: OpenShift Console URL

    • Webhook URL: The Pipelines as Code route or ingress URL. You can find it by executing the command echo https://$(oc get route -n pipelines-as-code el-pipelines-as-code-interceptor -o jsonpath='{.spec.host}').

      For Pipelines as Code installated by default using the Red Hat OpenShift Pipelines Operator, use the openshift-pipelines namespace instead of pipelines-as-code.

    • Webhook secret: An arbitrary secret. You can generate a secret by executing the command openssl rand -hex 20.

  4. Select the following Repository permissions:

    • Checks: Read & Write

    • Contents: Read & Write

    • Issues: Read & Write

    • Metadata: Read-only

    • Pull request: Read & Write

  5. Select the following Organization permissions:

    • Members: Readonly

    • Plan: Readonly

  6. Select the following User permissions:

    • Commit comment

    • Issue comment

    • Pull request

    • Pull request review

    • Pull request review comment

    • Push

  7. Click Create GitHub App.

  8. On the Details page of the newly created GitHub App, note the App ID displayed at the top.

  9. In the Private keys section, click Generate Private key to automatically generate and download a private key for the GitHub app. Securely store the private key for future reference and usage.

Configuring Pipelines as Code to access a GitHub App

To configure Pipelines as Code to access the newly created GitHub App, execute the following command:

+

$ oc -n <pipelines-as-code> create secret generic pipelines-as-code-secret \ (1)
        --from-literal github-private-key="$(cat <PATH_PRIVATE_KEY>)" \ (2)
        --from-literal github-application-id="<APP_ID>" \ (3)
        --from-literal webhook.secret="<WEBHOOK_SECRET>" (4)
1 For Pipelines as Code installated by default using the Red Hat OpenShift Pipelines Operator, use the openshift-pipelines namespace instead of pipelines-as-code.
2 The path to the private key you downloaded while configuring the GitHub App.
3 The App ID of the GitHub App.
4 The webhook secret provided when you created the GitHub App.

Pipelines as Code works automatically with GitHub Enterprise by detecting the header set from GitHub Enterprise and using it for the GitHub Enterprise API authorization URL.

Pipelines as Code command reference

The tkn-pac CLI tool offers the following capabilities:

  • Bootstrap Pipelines as Code installation and configuration.

  • Create a new Pipelines as Code repository.

  • List all Pipelines as Code repositories.

  • Describe a Pipelines as Code repository and the associated runs.

  • Generate a simple pipeline run to get started.

  • Resolve a pipeline run as if it was executed by Pipelines as Code.

You can use the commands corresponding to the capabilities for testing and experimentation, so that you don’t have to make changes to the Git repository containing the application source code.

Basic syntax

$ tkn pac [command or options] [arguments]

Global options

$ tkn pac --help

Utility commands

bootstrap

Table 1. Bootstrapping Pipelines as Code installation and configuration
Command Description

tkn pac bootstrap

Installs and configures Pipelines as Code for Git repository hosting service providers, such as GitHub and GitHub Enterprise.

tkn pac bootstrap --nightly

Installs the nightly build of Pipelines as Code.

tkn pac bootstrap --route-url <public_url_to_ingress_spec>

Overrides the OpenShift route URL.

By default, tkn pac bootstrap detects the OpenShift route, which is automatically associated with the Pipelines as Code controller service.

If you do not have an OpenShift Container Platform cluster, it asks you for the public URL that points to the ingress endpoint.

tkn pac bootstrap github-app

Create a GitHub application and secrets in the pipelines-as-code namespace.

repository

Table 2. Managing Pipelines as Code repositories
Command Description

tkn pac repo create

Creates a new Pipelines as Code repository and a namespace based on the pipeline run template.

tkn pac repo list

Lists all the Pipelines as Code repositories and displays the last status of the associated runs.

tkn pac repo describe

Describes a Pipelines as Code repository and the associated runs.

generate

Table 3. Generating pipeline runs using Pipelines as Code
Command Description

tkn pac generate

Generates a simple pipeline run.

When executed from the directory containing the source code, it automatically detects current Git information.

In addition, it uses basic language detection capability and adds extra tasks depending on the language.

For example, if it detects a setup.py file at the repository root, the pylint task is automatically added to the generated pipeline run.

resolve

Table 4. Resolving and executing pipeline runs using Pipelines as Code
Command Description

tkn pac resolve

Executes a pipeline run as if it is owned by the Pipelines as Code on service.

tkn pac resolve -f .tekton/pull-request.yaml | oc apply -f -

Displays the status of a live pipeline run that uses the template in .tekton/pull-request.yaml.

Combined with a Kubernetes installation running on your local machine, you can observe the pipeline run without generating a new commit.

If you run the command from a source code repository, it attempts to detect the current Git information and automatically resolve parameters such as current revision or branch.

tkn pac resolve -f .tekton/pr.yaml -p revision=main -p repo_name=<repository_name>

Executes a pipeline run by overriding default parameter values derived from the Git repository.

The -f option can also accept a directory path and apply the tkn pac resolve command on all .yaml or .yml files in that directory. You can also use the -f flag multiple times in the same command.

You can override the default information gathered from the Git repository by specifying parameter values using the -p option. For example, you can use a Git branch as a revision and a different repository name.

Customizing Pipelines as Code configuration

To customize Pipelines as Code, cluster administrators can configure the following parameters using the pipelines-as-code config map in the pipelines-as-code namespace:

Table 5. Customizing Pipelines as Code configuration
Parameter Description Default

application-name

The name of the application. For example, the name displayed in the GitHub Checks labels.

"Pipelines as Code CI"

max-keep-days

The number of the days for which the executed pipeline runs are kept in the pipelines-as-code namespace.

Note that this configmap setting does not affect the cleanups of a user’s pipeline runs, which are controlled by the annotations on the pipeline run definition in the user’s GitHub repository.

secret-auto-create

Indicates whether or not a secret should be automatically created using the token generated in the GitHub application. This secret can then be used with private repositories.

enabled

remote-tasks

When enabled, allows remote tasks from pipeline run annotations.

enabled

hub-url

The base URL for the Tekton Hub API.

https://hub.tekton.dev/

Additional resources