Creating CI/CD pipelines

Procedure

1. Perform one of the following steps:

   • For a public GitHub repository, set the value of the addChangedFiles parameter to true in the YAML configuration file shown below:

     apiVersion: triggers.tekton.dev/v1beta1
     kind: EventListener
     metadata:
       name: github-add-changed-files-pr-listener
     spec:
       triggers:
         - name: github-listener
           interceptors:
             - ref:
                 name: "github"
                 kind: ClusterInterceptor
                 apiVersion: triggers.tekton.dev
               params:
               - name: "secretRef"
                 value:
                   secretName: github-secret
                   secretKey: secretToken
               - name: "eventTypes"
                 value: ["pull_request", "push"]
               - name: "addChangedFiles"
                 value:
                   enabled: true
             - ref:
                 name: cel
               params:
               - name: filter
                 value: extensions.changed_files.matches('controllers/')
     ...

   • For a private GitHub repository, set the value of the addChangedFiles parameter to true and provide the access token details, secretName and secretKey in the YAML configuration file shown below:

     apiVersion: triggers.tekton.dev/v1beta1
     kind: EventListener
     metadata:
       name: github-add-changed-files-pr-listener
     spec:
       triggers:
         - name: github-listener
           interceptors:
             - ref:
                 name: "github"
                 kind: ClusterInterceptor
                 apiVersion: triggers.tekton.dev
               params:
               - name: "secretRef"
                 value:
                   secretName: github-secret
                   secretKey: secretToken
               - name: "eventTypes"
                 value: ["pull_request", "push"]
               - name: "addChangedFiles"
                 value:
                   enabled: true
                   personalAccessToken:
                     secretName: github-pat
                     secretKey: token
             - ref:
                 name: cel
               params:
               - name: filter
                 value: extensions.changed_files.matches('controllers/')
     ...

2. Save the configuration file.

Procedure

1. Create a secret string value.
2. Configure the GitHub webhook with that value.
3. Create a Kubernetes secret named secretRef that contains your secret value.
4. Pass the Kubernetes secret as a reference to your GitHub Interceptor.
5. Create an owners file and add the list of approvers into the approvers section.

6. Perform one of the following steps:

   • For a public GitHub repository, set the value of the githubOwners parameter to true in the YAML configuration file shown below:

     apiVersion: triggers.tekton.dev/v1beta1
     kind: EventListener
     metadata:
       name: github-owners-listener
     spec:
       triggers:
         - name: github-listener
           interceptors:
             - ref:
                 name: "github"
                 kind: ClusterInterceptor
                 apiVersion: triggers.tekton.dev
               params:
                 - name: "secretRef"
                   value:
                     secretName: github-secret
                     secretKey: secretToken
                 - name: "eventTypes"
                   value: ["pull_request", "issue_comment"]
                 - name: "githubOwners"
                   value:
                     enabled: true
                     checkType: none
     ...

   • For a private GitHub repository, set the value of the githubOwners parameter to true and provide the access token details, secretName and secretKey in the YAML configuration file shown below:

     apiVersion: triggers.tekton.dev/v1beta1
     kind: EventListener
     metadata:
       name: github-owners-listener
     spec:
       triggers:
         - name: github-listener
           interceptors:
             - ref:
                 name: "github"
                 kind: ClusterInterceptor
                 apiVersion: triggers.tekton.dev
               params:
                 - name: "secretRef"
                   value:
                     secretName: github-secret
                     secretKey: secretToken
                 - name: "eventTypes"
                   value: ["pull_request", "issue_comment"]
                 - name: "githubOwners"
                   value:
                     enabled: true
                     personalAccessToken:
                       secretName: github-token
                       secretKey: secretToken
                     checkType: all
     ...

     Note

     The checkType parameter is used to specify the GitHub owners who need authentication. You can set its value to orgMembers, repoMembers, or all.

7. Save the configuration file.

Procedure

1. In the +Add view of the Developer perspective, click the Pipeline tile to see the Pipeline builder page.

2. Configure the pipeline using either the Pipeline builder view or the YAML view.

   Note

   The Pipeline builder view supports a limited number of fields whereas the YAML view supports all available fields. Optionally, you can also use the Operator-installed, reusable snippets and samples to create detailed pipelines.

   Figure 2.1. YAML view

   

3. Configure your pipeline by using Pipeline builder:

   1. In the Name field, enter a unique name for the pipeline.

   2. In the Tasks section:

      1. Click Add task.
      2. Search for a task using the quick search field and select the required task from the displayed list.

      3. Click Add or Install and add. In this example, use the s2i-nodejs task.

         Note

         The search list contains all the Tekton Hub tasks and tasks available in the cluster. Also, if a task is already installed it will show Add to add the task whereas it will show Install and add to install and add the task. It will show Update and add when you add the same task with an updated version.

         • To add sequential tasks to the pipeline:

           • Click the plus icon to the right or left of the task → click Add task.
           • Search for a task using the quick search field and select the required task from the displayed list.

           • Click Add or Install and add.

             Figure 2.2. Pipeline builder

             

         • To add a final task:

           • Click the Add finally task → Click Add task.
           • Search for a task using the quick search field and select the required task from the displayed list.
           • Click Add or Install and add.

   3. In the Resources section, click Add Resources to specify the name and type of resources for the pipeline run. These resources are then used by the tasks in the pipeline as inputs and outputs. For this example:

      1. Add an input resource. In the Name field, enter Source, and then from the Resource Type drop-down list, select Git.

      2. Add an output resource. In the Name field, enter Img, and then from the Resource Type drop-down list, select Image.

         Note

         A red icon appears next to the task if a resource is missing.

   4. Optional: The Parameters for a task are pre-populated based on the specifications of the task. If required, use the Add Parameters link in the Parameters section to add additional parameters.
   5. In the Workspaces section, click Add workspace and enter a unique workspace name in the Name field. You can add multiple workspaces to the pipeline.

   6. In the Tasks section, click the s2i-nodejs task to see the side panel with details for the task. In the task side panel, specify the resources and parameters for the s2i-nodejs task:

      1. If required, in the Parameters section, add more parameters to the default ones, by using the $(params.<param-name>) syntax.
      2. In the Image section, enter Img as specified in the Resources section.
      3. Select a workspace from the source drop-down under Workspaces section.
   7. Add resources, parameters, and workspaces to the openshift-client task.
4. Click Create to create and view the pipeline in the Pipeline Details page.
5. Click the Actions drop-down menu then click Start, to see the Start Pipeline page.
6. The Workspaces section lists the workspaces you created earlier. Use the respective drop-down to specify the volume source for your workspace. You have the following options: Empty Directory, Config Map, Secret, PersistentVolumeClaim, or VolumeClaimTemplate.

Procedure

1. In the Developer perspective, choose the namespace or project in which you want to add your GitHub repository.
2. Navigate to Pipelines using the left navigation pane.
3. Click Create → Repository on the right side of the Pipelines page.
4. Enter your Git Repo URL and the console automatically fetches the repository name.

5. Click Show configuration options. By default, you see only one option Setup a webhook. If you have a GitHub application configured, you see two options:

   • Use GitHub App: Select this option to install your GitHub application in your repository.
   • Setup a webhook: Select this option to add a webhook to your GitHub application.

6. Set up a webhook using one of the following options in the Secret section:

   • Setup a webhook using Git access token:

     1. Enter your personal access token.

     2. Click Generate corresponding to the Webhook secret field to generate a new webhook secret.

        
        Note

        You can click the link below the Git access token field if you do not have a personal access token and want to create a new one.

   • Setup a webhook using Git access token secret:

     • Select a secret in your namespace from the dropdown list. Depending on the secret you selected, a webhook secret is automatically generated.

       

7. Add the webhook secret details to your GitHub repository:

   1. Copy the webhook URL and navigate to your GitHub repository settings.
   2. Click Webhooks → Add webhook.
   3. Copy the Webhook URL from the developer console and paste it in the Payload URL field of the GitHub repository settings.
   4. Select the Content type.
   5. Copy the Webhook secret from the developer console and paste it in the Secret field of the GitHub repository settings.
   6. Select one of the SSL verification options.
   7. Select the events to trigger this webhook.
   8. Click Add webhook.
8. Navigate back to the developer console and click Add.
9. Read the details of the steps that you have to perform and click Close.
10. View the details of the repository you just created.

Procedure

1. In the Pipelines view of the Developer perspective, select a project from the Project drop-down list to see the pipelines in that project.

2. Click the required pipeline to see the Pipeline details page.

   By default, the Details tab displays a visual representation of all the serial tasks, parallel tasks, finally tasks, and when expressions in the pipeline. The tasks and the finally tasks are listed in the lower right portion of the page.

   To view the task details, click the listed Tasks and Finally tasks. In addition, you can do the following:

   • Use the zoom in, zoom out, fit to screen, and reset view features using the standard icons displayed in the lower left corner of the Pipeline details visualization.
   • Change the zoom factor of the pipeline visualization using the mouse wheel.

   • Hover over the tasks and see the task details.

     Figure 2.3. Pipeline details

     

3. Optional: On the Pipeline details page, click the Metrics tab to see the following information about pipelines:

   • Pipeline Success Ratio
   • Number of Pipeline Runs
   • Pipeline Run Duration

   • Task Run Duration

     You can use this information to improve the pipeline workflow and eliminate issues early in the pipeline lifecycle.

4. Optional: Click the YAML tab to edit the YAML file for the pipeline.

5. Optional: Click the Pipeline Runs tab to see the completed, running, or failed runs for the pipeline.

   The Pipeline Runs tab provides details about the pipeline run, the status of the task, and a link to debug failed pipeline runs. Use the Options menu to stop a running pipeline, to rerun a pipeline using the same parameters and resources as that of the previous pipeline execution, or to delete a pipeline run.

   • Click the required pipeline run to see the Pipeline Run details page. By default, the Details tab displays a visual representation of all the serial tasks, parallel tasks, finally tasks, and when expressions in the pipeline run. The results for successful runs are displayed under the Pipeline Run results pane at the bottom of the page. Additionally, you would only be able to see tasks from Tekton Hub which are supported by the cluster. While looking at a task, you can click the link beside it to jump to the task documentation.

     Note

     The Details section of the Pipeline Run Details page displays a Log Snippet of the failed pipeline run. Log Snippet provides a general error message and a snippet of the log. A link to the Logs section provides quick access to the details about the failed run.

   • On the Pipeline Run details page, click the Task Runs tab to see the completed, running, and failed runs for the task.

     The Task Runs tab provides information about the task run along with the links to its task and pod, and also the status and duration of the task run. Use the Options menu to delete a task run.

     Note

     The TaskRuns list page features a Manage columns button, which you can also use to add a Duration column.

   • Click the required task run to see the Task Run details page. The results for successful runs are displayed under the Task Run results pane at the bottom of the page.

     Note

     The Details section of the Task Run details page displays a Log Snippet of the failed task run. Log Snippet provides a general error message and a snippet of the log. A link to the Logs section provides quick access to the details about the failed task run.

6. Click the Parameters tab to see the parameters defined in the pipeline. You can also add or edit additional parameters, as required.
7. Click the Resources tab to see the resources defined in the pipeline. You can also add or edit additional resources, as required.

1. In the Pipelines view of the Developer perspective, click the Options menu adjoining a pipeline, and select Start.

2. The Start Pipeline dialog box displays the Git Resources and the Image Resources based on the pipeline definition.

   Note

   For pipelines created using the From Git option, the Start Pipeline dialog box also displays an APP_NAME field in the Parameters section, and all the fields in the dialog box are prepopulated by the pipeline template.

   1. If you have resources in your namespace, the Git Resources and the Image Resources fields are prepopulated with those resources. If required, use the drop-downs to select or create the required resources and customize the pipeline run instance.

3. Optional: Modify the Advanced Options to add the credentials that authenticate the specified private Git server or the image registry.

   1. Under Advanced Options, click Show Credentials Options and select Add Secret.

   2. In the Create Source Secret section, specify the following:

      1. A unique Secret Name for the secret.
      2. In the Designated provider to be authenticated section, specify the provider to be authenticated in the Access to field, and the base Server URL.

      3. Select the Authentication Type and provide the credentials:

         • For the Authentication Type Image Registry Credentials, specify the Registry Server Address that you want to authenticate, and provide your credentials in the Username, Password, and Email fields.

           Select Add Credentials if you want to specify an additional Registry Server Address.

         • For the Authentication Type Basic Authentication, specify the values for the UserName and Password or Token fields.

         • For the Authentication Type SSH Keys, specify the value of the SSH Private Key field.

           Note

           For basic authentication and SSH authentication, you can use annotations such as:

           • tekton.dev/git-0: https://github.com
           • tekton.dev/git-1: https://gitlab.com.
      4. Select the check mark to add the secret.

   You can add multiple secrets based upon the number of resources in your pipeline.

4. Click Start to start the pipeline.

5. The PipelineRun details page displays the pipeline being executed. After the pipeline starts, the tasks and steps within each task are executed. You can:

   • Use the zoom in, zoom out, fit to screen, and reset view features using the standard icons, which are in the lower left corner of the PipelineRun details page visualization.
   • Change the zoom factor of the pipelinerun visualization using the mouse wheel. At specific zoom factors, the background color of the tasks changes to indicate the error or warning status.
   • Hover over the tasks to see the details, such as the time taken to execute each step, task name, and task status.
   • Hover over the tasks badge to see the total number of tasks and tasks completed.
   • Click on a task to see the logs for each step in the task.
   • Click the Logs tab to see the logs relating to the execution sequence of the tasks. You can also expand the pane and download the logs individually or in bulk, by using the relevant button.

   • Click the Events tab to see the stream of events generated by a pipeline run.

     You can use the Task Runs, Logs, and Events tabs to assist in debugging a failed pipeline run or a failed task run.

     Figure 2.4. Pipeline run details

     

Procedure

1. Click Topology in the left navigation panel.
2. Click the application to display Pipeline Runs in the side panel.

3. In Pipeline Runs, click Start Last Run to start a new pipeline run with the same parameters and resources as the previous one. This option is disabled if a pipeline run has not been initiated. You can also start a pipeline run when you create it.

   Figure 2.5. Pipelines in Topology view

   

Procedure

1. In the Pipelines view of the Developer perspective, select the pipeline you want to edit to see the details of the pipeline. In the Pipeline Details page, click Actions and select Edit Pipeline.

2. On the Pipeline builder page, you can perform the following tasks:

   • Add additional tasks, parameters, or resources to the pipeline.
   • Click the task you want to modify to see the task details in the side panel and modify the required task details, such as the display name, parameters, and resources.
   • Alternatively, to delete the task, click the task, and in the side panel, click Actions and select Remove Task.
3. Click Save to save the modified pipeline.

Procedure

1. In the Pipelines view of the Developer perspective, click the Options menu adjoining a Pipeline, and select Delete Pipeline.
2. In the Delete Pipeline confirmation prompt, click Delete to confirm the deletion.

Procedure

1. In the Administrator perspective of the web console, select Operators → Installed Operators.
2. Click Red Hat OpenShift Pipelines in the table of Operators.
3. In the right pane on the screen, check the status label under Console plugin. The label is either Enabled or Disabled.
4. If the label is Disabled, click this label. In the window that displays, select Enable and then click Save.

Procedure

1. In the Administrator perspective of the web console, select Pipelines → Overview.

   A statistics overview displays. This overview includes the following information: A graph reflecting the number and status of pipeline runs over a time period The total, average, and maximum durations of pipeline execution over the same period. ** The total number of pipeline runs over the same period.

   A table of pipelines also displays. This table lists all pipelines that were run in the time period, showing their duration and success rate.

2. Optional: Change the settings of the statistics display as necessary:

   • Project: The project or namespace to display statistics for.
   • Time range: The time period to display statistics for.
   • Refresh interval: How often Red Hat OpenShift Pipelines must update the data in the window while you are viewing it.

Procedure

1. In the Administrator perspective of the web console, select Pipelines → Pipelines.
2. Click a pipeline in the list of pipelines. The Pipeline details view displays.

3. Click the Metrics tab.

   A statistics overview displays. This overview includes the following information: A graph reflecting the number and status of pipeline runs over a time period The total, average, and maximum durations of pipeline execution over the same period. ** The total number of pipeline runs over the same period.

4. Optional: Change the settings of the statistics display as necessary:

   • Project: The project or namespace to display statistics for.
   • Time range: The time period to display statistics for.
   • Refresh interval: How often Red Hat OpenShift Pipelines must update the data in the window while you are viewing it.

Procedure

1. To edit the TektonConfig custom resource, enter the following command:

   $ oc edit TektonConfig config

2. In the TektonConfig custom resource, edit the pipeline.hub-resolver-config spec:

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     pipeline:
       hub-resolver-config:
         default-tekton-hub-catalog: Tekton 1
         default-artifact-hub-task-catalog: tekton-catalog-tasks 2
         default-artifact-hub-pipeline-catalog: tekton-catalog-pipelines 3
         defailt-kind: pipeline 4
         default-type: tekton 5
         tekton-hub-api: "https://my-custom-tekton-hub.example.com" 6
         artifact-hub-api: "https://my-custom-artifact-hub.example.com" 7

   1

   The default Tekton Hub catalog for pulling a resource.

   2

   The default Artifact Hub catalog for pulling a task resource.

   3

   The default Artifact Hub catalog for pulling a pipeline resource.

   4

   The default object kind for references.

   5

   The default hub for pulling a resource, either artifact for Artifact Hub or tekton for Tekton Hub.

   6

   The Tekton Hub API used, if the default-type option is set to tekton.

   7

   Optional: The Artifact Hub API used, if the default-type option is set to artifact.

   Important

   If you set the default-type option to tekton, you must configure your own instance of the Tekton Hub by setting the tekton-hub-api value.

   If you set the default-type option to artifact then the resolver uses the public hub API at https://artifacthub.io/ by default. You can configure your own Artifact Hub API by setting the artifact-hub-api value.

Procedure

1. To edit the TektonConfig custom resource, enter the following command:

   $ oc edit TektonConfig config

2. In the TektonConfig custom resource, edit the pipeline.bundles-resolver-config spec:

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     pipeline:
       bundles-resolver-config:
         default-service-account: pipelines 1
         default-kind: task 2

   1

   The default service account name to use for bundle requests.

   2

   The default layer kind in the bundle image.

Procedure

1. To edit the TektonConfig custom resource, enter the following command:

   $ oc edit TektonConfig config

2. In the TektonConfig custom resource, edit the pipeline.cluster-resolver-config spec:

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     pipeline:
       cluster-resolver-config:
         default-kind: pipeline 1
         default-namespace: namespace1 2
         allowed-namespaces: namespace1, namespace2 3
         blocked-namespaces: namespace3, namespace4 4

   1

   The default resource kind to fetch, if not specified in parameters.

   2

   The default namespace for fetching resources, if not specified in parameters.

   3

   A comma-separated list of namespaces that the resolver is allowed to access. If this key is not defined, all namespaces are allowed.

   4

   An optional comma-separated list of namespaces which the resolver is blocked from accessing. If this key is not defined, all namespaces are allowed.

Procedure

1. To edit the TektonConfig custom resource, enter the following command:

   $ oc edit TektonConfig config

2. In the TektonConfig custom resource, edit the pipeline.git-resolver-config spec:

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     pipeline:
       git-resolver-config:
         default-revision: main 1
         fetch-timeout: 1m 2
         default-url: https://github.com/tektoncd/catalog.git 3

   1

   The default Git revision to use if none is specified.

   2

   The maximum time any single Git clone resolution may take, for example, 1m, 2s, 700ms. Red Hat OpenShift Pipelines also enforces a global maximum timeout of 1 minute on all resolution requests.

   3

   The default Git repository URL for anonymous cloning if none is specified.

Procedure

1. To edit the TektonConfig custom resource, enter the following command:

   $ oc edit TektonConfig config

2. In the TektonConfig custom resource, edit the pipeline.git-resolver-config spec:

   apiVersion: operator.tekton.dev/v1alpha1
   kind: TektonConfig
   metadata:
     name: config
   spec:
     pipeline:
       git-resolver-config:
         default-revision: main 1
         fetch-timeout: 1m 2
         scm-type: github 3
         server-url: api.internal-github.com 4
         api-token-secret-name: github-auth-secret 5
         api-token-secret-key: github-auth-key 6
         api-token-secret-namespace: github-auth-namespace 7
         default-org: tektoncd 8

   1

   The default Git revision to use if none is specified.

   2

   The maximum time any single Git clone resolution may take, for example, 1m, 2s, 700ms. Red Hat OpenShift Pipelines also enforces a global maximum timeout of 1 minute on all resolution requests.

   3

   The SCM provider type.

   4

   The base URL for use with the authenticated SCM API. This setting is not required if you are using github.com, gitlab.com, or BitBucket Cloud.

   5

   The name of the secret that contains the SCM provider API token.

   6

   The key within the token secret that contains the token.

   7

   The namespace containing the token secret, if not default.

   8

   Optional: The default organization for the repository, when using the authenticated API. This organization is used if you do not specify an organization in the resolver parameters.

Procedure

1. To specify a remote pipeline or task from a Git repository, use the following reference format in the pipelineRef or taskRef spec:

   # ...
     resolver: git
     params:
     - name: url
       value: <git_repository_url>
     - name: revision
       value: <branch_name>
     - name: pathInRepo
       value: <path_in_repository>
   # ...

   Table 3.4. Supported parameters for the Git resolver

   Parameter	Description	Example value
   url	The URL of the repository, when using anonymous cloning.	https://github.com/tektoncd/catalog.git
   repo	The repository name, when using the authenticated SCM API.	test-infra
   org	The organization for the repository, when using the authenticated SCM API.	tektoncd
   revision	The Git revision in the repository. You can specify a branch name, a tag name, or a commit SHA hash.	aeb957601cf41c012be462827053a21a420befca main v0.38.2
   pathInRepo	The path name of the YAML file in the repository.	task/golang-build/0.3/golang-build.yaml

   Note

   To clone and fetch the repository anonymously, use the url parameter. To use the authenticated SCM API, use the repo parameter. Do not specify the url parameter and the repo parameter together.

   If the pipeline or task requires additional parameters, specify values for these parameters in the params section of the specification of the pipeline, pipeline run, or task run. The params section of the pipelineRef or taskRef specification must contain only the parameters that the resolver supports.