1. Documentation
    2. history bug_report picture_as_pdf
×

Using Pipelines as Code

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 in the openshift-pipelines namespace when you install the Red Hat OpenShift Pipelines Operator. For more details, see Installing OpenShift Pipelines in the Additional resources section.

To enable the default installation of Pipelines as Code with the Red Hat OpenShift Pipelines Operator, set the value of the enable parameter to true in the TektonConfig custom resource:

...
 spec:
    platforms:
      openshift:
        pipelinesAsCode:
          enable: true
          settings:
            application-name: Pipelines as Code CI
            auto-configure-new-github-repo: "false"
            bitbucket-cloud-check-source-ip: "true"
            hub-catalog-name: tekton
            hub-url: https://api.hub.tekton.dev/v1
            remote-tasks: "true"
            secret-auto-create: "true"
...

If you want to disable the default installation of Pipelines as Code with the Operator, set the value of the enable parameter to false.

Installing Pipelines as Code CLI

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

You can install the tkn-pac and opc version 1.9.0 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

  • GitLab

  • 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 running the command echo https://$(oc get route -n openshift-pipelines pipelines-as-code-controller -o jsonpath='{.spec.host}').

      If Pipelines as Code is installed without using the Red Hat OpenShift Pipelines Operator, use the pipelines-as-code namespace instead of openshift-pipelines.

    • 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:

    • Check run

    • Issue comment

    • Pull request

    • 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.

  10. Install the created App on a repository that you want to use with Pipelines as Code.

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 openshift-pipelines 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 If Pipelines as Code is installed without using the Red Hat OpenShift Pipelines Operator, use the pipelines-as-code namespace instead of openshift-pipelines.
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.

Creating a GitHub App in administrator perspective

As a cluster administrator, you can configure your GitHub App with the OpenShift Container Platform cluster to use Pipelines as Code. This configuration allows you to execute a set of tasks required for build deployment.

Prerequisites

You have installed the Red Hat OpenShift Pipelines pipelines-1.8 operator from the Operator Hub.

Procedure

  1. In the administrator perspective, navigate to Pipelines using the navigation pane.

  2. Click Setup GitHub App on the Pipelines page.

  3. Enter your GitHub App name. For example, pipelines-ci-clustername-testui.

  4. Click Setup.

  5. Enter your Git password when prompted in the browser.

  6. Click Create GitHub App for <username>, where <username> is your GitHub user name.

Verification

After successful creation of the GitHub App, the OpenShift Container Platform web console opens and displays the details about the application.