Using manual approval in OpenShift Pipelines | Creating CI/CD pipelines

Enabling the manual approval gate controller
Specifying a manual approval task
Approving a manual approval task
- Approving a manual approval task by using the web console
- Approving a manual approval task by using the command line

You can specify a manual approval task in a pipeline. When the pipeline reaches this task, it pauses and awaits approval from one or several OpenShift Container Platform users. If any of the users chooses to rejects the task instead of approving it, the pipeline fails. The manual approval gate controller provides this functionality.

The manual approval gate 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.

Enabling the manual approval gate controller

To use manual approval tasks, you must first enable the manual approval gate controller.

Prerequisites

You installed the Red Hat OpenShift Pipelines Operator in your cluster.
You are logged on to the cluster using the oc command-line utility.
You have administrator permissions for the openshift-pipelines namespace.

Procedure

Create a file named manual-approval-gate-cr.yaml with the following manifest for the ManualApprovalGate custom resource (CR):

apiVersion: operator.tekton.dev/v1alpha1
kind: ManualApprovalGate
metadata:
  name: manual-approval-gate
spec:
  targetNamespace: openshift-pipelines

Apply the ManualApprovalGate CR by entering the following command:
```
$ oc apply -f manual-approval-gate-cr.yaml
```
Verify that the manual approval gate controller is running by entering the following command:
```
$ oc get manualapprovalgates.operator.tekton.dev
```
Example output
```
NAME                   VERSION    READY   REASON
manual-approval-gate   v0.1.0	    True
```
Ensure that the READY status is True. If it is not True, wait for a few minutes and enter the command again. The controller might take some time to reach a ready state.

Specifying a manual approval task

You can specify a manual approval task in your pipeline. When the execution of a pipeline run reaches this task, the pipeline run stops and awaits approval from one or several users.

Prerequisites

You enabled the manual approver gate controller.
You created a YAML specification of a pipeline.

Procedure

Specify an ApprovalTask in the pipeline, as shown in the following example:

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: example-manual-approval-pipeline
spec:
  tasks:
# ...
  - name: example-manual-approval-task
    taskRef:
      apiVersion: openshift-pipelines.org/v1alpha1
      kind: ApprovalTask
    params:
    - name: approvers
      value:
      - user1
      - user2
      - user3
    - name: description
      value: Example manual approval task - please approve or reject
    - name: numberOfApprovalsRequired
      value: '2'
    - name: timeout
      value: '60m'
# ...

Table 1. Parameters for a manual approval task
Parameter	Type	Description
`approvers`	array	The OpenShift Container Platform users who can approve the task.
`description`	string	Optional: The description of the approval task. OpenShift Pipelines displays the description to the user who can approve or reject the task.
`numberOfApprovalsRequired`	string	The number of approvals from different users that the task requires.
`timeout`	string	Optional: The timeout period for approval. If the task does not receive the configured number of approvals during this period, the pipeline run fails. The default timeout is 1 hour.

Approving a manual approval task

When you run a pipeline that includes an approval task and the execution reaches the approval task, the pipeline run pauses and waits for user approval or rejection.

Users can approve or reject the task by using either the web console or the opc command line utility.

If any one of the approvers configured in the task rejects the task, the pipeline run fails.

If one user approves the task but the configured number of approvals is still not reached, the same user can change to rejecting the task and the pipeline run fails

Approving a manual approval task by using the web console

You can approve or reject a manual approval task by using the OpenShift Container Platform web console.

If you are listed as an approver in a manual approval task and a pipeline run reaches this task, the web console displays a notification. You can view a list of tasks that require your approval and approve or reject these tasks.

Prerequisites

You enabled the OpenShift Pipelines console plugin.

Procedure

View a list of tasks that you can approve by completing one of the following actions:
- When a notification about a task requiring your approval displays, click Go to Approvals tab in this notification.
- In the Administrator perspective menu, select Pipelines → Pipelines and then click the Approvals tab.
- In the Developer perspective menu, select Pipelines and then click the Approvals tab.
- In the PipelineRun details window, in the Details tab, click the rectangle that represents the manual approval task. The list displays only the approval for this task.
- In the PipelineRun details window, click the ApprovalTasks tab. The list displays only the approval for this pipeline run.
In the list of approval tasks, in the line that represents the task that you want to approve, click the icon and then select one of the following options:
- To approve the task, select Approve.
- To reject the task, select Reject.
Enter a message in the Reason field.
Click Submit.

Additional resources

Enabling the OpenShift Pipelines console plugin

Approving a manual approval task by using the command line

You can approve or reject a manual approval task by using the opc command-line utility. You can view a list of tasks for which you are an approver and approve or reject the tasks that are pending approval.

Prerequisites

You downloaded and installed the opc command-line utility. This utility is available in the same package as the tkn command-line utility.
You are logged on to the cluster using the oc command-line utility.

Procedure

View a list of manual approval tasks for which you are listed as an approver by entering the following command:

$ opc approvaltask list

Example output

NAME                                     NumberOfApprovalsRequired   PendingApprovals   Rejected   STATUS
manual-approval-pipeline-01w6e1-task-2   2                           0                  0          Approved
manual-approval-pipeline-6ywv82-task-2   2                           2                  0          Rejected
manual-approval-pipeline-90gyki-task-2   2                           2                  0          Pending
manual-approval-pipeline-jyrkb3-task-2   2                           1                  1          Rejected

Optional: To view information about a manual approval task, including its name, namespace, pipeline run name, list of approvers, and current status, enter the following command:
```
$ opc approvaltask describe <approval_task_name>
```
Approve or reject a manual approval task as necessary:
- To approve a manual approval task, enter the following command:
  $ opc approvaltask approve <approval_task_name>
  Optionally, you can specify a message for the approval by using the -m parameter:
  $ opc approvaltask approve <approval_task_name> -m <message>
- To reject a manual approval task, enter the following command:
  $ opc approvaltask reject <approval_task_name>
  Optionally, you can specify a message for the rejection by using the -m parameter:
  $ opc approvaltask reject <approval_task_name> -m <message>

Additional resources

Installing tkn