Chapter 4. Using manual approval in OpenShift Pipelines
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.
4.1. 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
occommand-line utility. -
You have administrator permissions for the
openshift-pipelinesnamespace.
Procedure
Create a file named
manual-approval-gate-cr.yamlwith the following manifest for theManualApprovalGatecustom resource (CR):apiVersion: operator.tekton.dev/v1alpha1 kind: ManualApprovalGate metadata: name: manual-approval-gate spec: targetNamespace: openshift-pipelines
Apply the
ManualApprovalGateCR 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
READYstatus isTrue. If it is notTrue, wait for a few minutes and enter the command again. The controller might take some time to reach a ready state.
4.2. 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
ApprovalTaskin 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 4.1. Parameters for a manual approval task Parameter Type Description approversarray
The OpenShift Container Platform users who can approve the task.
descriptionstring
Optional: The description of the approval task. OpenShift Pipelines displays the description to the user who can approve or reject the task.
numberOfApprovalsRequiredstring
The number of approvals from different users that the task requires.
timeoutstring
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.
4.3. 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
4.3.1. 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
4.3.2. 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
opccommand-line utility. This utility is available in the same package as thetkncommand-line utility. -
You are logged on to the cluster using the
occommand-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
-mparameter:$ 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
-mparameter:$ opc approvaltask reject <approval_task_name> -m <message>
Additional resources
