Manual Approval Gate for Tekton Pipelines
TOC
Feature OverviewUse CasesPrerequisitesSteps1. Declare the approval step in a pipelinenumberOfApprovalsRequired parameter2. Monitor approval status3. Approve or rejectUser approvalsGroup approvals4. Extend PipelineRun timeouts for long approvalsOperation ResultsApprovalTask LifecycleTroubleshootingUser and group identifiersLearn MoreFeature Overview
Manual Approval Gate lets pipeline authors pause a PipelineRun until designated approvers review and approve the operation. Behind the scenes, the Operator-provided controller creates an ApprovalTask resource for every approval step, tracks approver responses, and writes the result back to the originating CustomRun.
Use Cases
- Enforcing human checkpoints before deploying to production or performing destructive maintenance.
- Implementing multi-person approval policies by combining individuals and groups with
numberOfApprovalsRequired. - Auditing who approved or rejected a change by querying
ApprovalTaskstatus fields or CLI output.
Prerequisites
- A cluster administrator has deployed
Manual Approval Gate. If not, refer to the deployment guide. - You can create or edit
Pipeline/PipelineRunobjects in the target namespace. - Approvers can patch
approvaltasks.openshift-pipelines.orgresources (typically viakubectl) in the target namespace. - The
jqCLI, used to readApprovalTaskfields in the steps below.
Steps
1. Declare the approval step in a pipeline
When the pipeline reaches wait-for-approval, Tekton emits a CustomRun. The approval controller creates an ApprovalTask with your parameters and keeps the PipelineRun pending until quorum is met or a rejection occurs.
numberOfApprovalsRequired parameter
Approvals are counted per distinct user name. For a group: approver, each group member who approves counts separately, so the value can be larger than the number of entries in approvers.
If numberOfApprovalsRequired is larger than the number of users who can actually approve, no error is reported. The ApprovalTask stays pending until an approver rejects it or the approval times out; on timeout, the controller marks the ApprovalTask as rejected and fails the CustomRun.
This applies to the timeout of the approval step. If the whole PipelineRun times out first, Tekton cancels the approval step, but the ApprovalTask stays pending and its CustomRun keeps the Succeeded condition Unknown until the approval timeout has passed since the ApprovalTask was created. Then the controller marks the ApprovalTask as rejected and fails the CustomRun, although nobody rejected it. The approval timeout is the spec.timeout of the step's CustomRun, or 60 minutes when that field is empty. When the step sets a timeout, such as "24h" above, the field holds that value, unless a taskRunSpecs entry of the PipelineRun sets another timeout for the step; without a step timeout, read the field on the CustomRun. Check the PipelineRun status before you act on a pending ApprovalTask.
Then start a PipelineRun of the Pipeline. Its timeouts must be longer than the approval window (see step 4). Save the following YAML as deploy-with-approval-run.yaml and create it in the namespace of the Pipeline:
When the run reaches wait-for-approval, the ApprovalTask deploy-with-approval-run-wait-for-approval appears. The steps below use this name.
2. Monitor approval status
The output above is abbreviated and shows the ApprovalTask before anyone responds: State is pending. Approvers Response appears after the first response, and Approvals Received only after the first approval: it counts approvals, and a rejection alone does not add it.
Important status fields:
status.state: overall gate state such aspending,approved, orrejected.status.approvalsRequired/status.approvalsReceived: quorum tracking (the received count counts approvals and appears only after the first approval; a rejection alone does not add it).status.approversResponse: per-user/group outcome plus messages, useful for auditing.
3. Approve or reject
User approvals
First, inspect the approvers list to determine the correct index:
The examples below use --as (and --as-group) to show which identity sends each request. An approver who runs the command with their own credentials leaves these flags out; see the tip at the end of this step.
To approve as a user:
To reject as a user:
Group approvals
The group walk-through below needs two approvals. Before you start the PipelineRun in step 1, set numberOfApprovalsRequired to "2" in the Pipeline. With the value "1" from step 1, the first approval completes the ApprovalTask (state: approved). If you have already run step 1, delete that run first, because step 1 creates it under the fixed name deploy-with-approval-run. Then wait until kubectl get approvaltasks.openshift-pipelines.org no longer lists deploy-with-approval-run-wait-for-approval:
When a group is configured as an approver, individual members of that group can submit their approval by adding their response to the users array under the group entry. Multiple group members can approve independently, and each approval counts toward the approvalsReceived total.
Initially, the group approver entry does not have a users field:
The first group member creates the users array and sets the group's input to approve:
Subsequent group members append to the existing users array and update the group's input:
To reject as a group member:
After the bob and carol patches, check the group entry and status to see all members' responses:
In this example, both bob and carol from the release-managers group have approved. Each approval from a group member increments approvalsReceived separately, so two group member approvals count as two approvals toward the required total. The status.approversResponse shows detailed approval information including individual group members' responses.
Key points for group approvals:
- Each group member must perform two required operations: add their entry to the
usersarray AND set the group'sinput(eitherapproveorreject). Optionally, they can also set the group'smessage - The first group member creates the
usersarray using path/spec/approvers/<index>/userswith an array value - Subsequent members append to the array using path
/spec/approvers/<index>/users/-where-appends to the array end - A user entry in the
usersarray hasnameandinput, and may also have its ownmessage. That message appears in the member'sgroupMembersentry instatus.approversResponse; the entries in the output above have none because the patches set none - The group-level
messagefield is optional and shared; it will be overwritten by subsequent responses if they provide a new message - Each group member approval increments
approvalsReceivedindependently - Multiple members from the same group can approve, and each counts toward the required total
- The
status.approversResponsefield tracks detailed approval information including individual group members - Each group member patches with their own identity: the webhook matches the user name and groups of the request against the approver entries
The controller sets the corresponding CustomRun and PipelineRun to Succeeded or Failed accordingly: approvals accumulate until numberOfApprovalsRequired is satisfied, while any rejection immediately fails that section of the pipeline.
Tip: Approvers patch the
ApprovalTaskas themselves. The validation webhook reads the user name and groups of the request and allows you to modify only the entry that matches them. Use--as <username>and--as-group <group>only when you act as another identity, for example in a test; this needs impersonation rights in RBAC. For example,kubectl patch ... --as bob --as-group release-managerssends the request as userbobin therelease-managersgroup.
4. Extend PipelineRun timeouts for long approvals
Set the approval window with the timeout field of the approval step (timeout: "24h" in step 1). If an approval could take hours or days, size both PipelineRun.spec.timeouts.pipeline and PipelineRun.spec.timeouts.tasks to cover the tasks that run before the approval step, the approval step timeout, and the tasks that run after it: both are measured from the start of the PipelineRun, and timeouts.tasks covers all non-finally tasks. The PipelineRun in step 1 sets both to 72h, which leaves 48 hours for the other tasks around the "24h" approval step.
If the PipelineRun timeouts are shorter, the PipelineRun might expire first, leaving the approval unresolved.
Operation Results
kubectl get approvaltasks -o yamlshows each approval gate withstateand quorum-related fields (thestatus.approvalsReceivedfield counts approvals and appears after the first approval).PipelineRunstatus reflects the approval outcome: when approved, downstream tasks resume; when rejected, thePipelineRunfails (SucceededisFalse, reasonFailed). The approval step'sCustomRunshowsApproval Task denied, andstatus.approversResponseof theApprovalTaskshows who rejected it and their message.- Dispatch logs or
kubectl get approvaltask -o yamloutput provide the approval history for auditing. TheApprovalTaskis deleted together with itsPipelineRun; see ApprovalTask Lifecycle.
ApprovalTask Lifecycle
The controller creates each ApprovalTask with the same name and namespace as its CustomRun, and sets that CustomRun as its controller owner. The CustomRun is in turn owned by the PipelineRun. Because of this ownership chain (PipelineRun → CustomRun → ApprovalTask), Kubernetes garbage collection deletes the ApprovalTask when the PipelineRun is deleted. The approval controller has no separate retention or cleanup for ApprovalTask objects.
The approval record kept on the ApprovalTask, such as status.approversResponse, therefore exists only as long as the PipelineRun. When the PipelineRun is deleted, manually or by Tekton Pruner through ttlSecondsAfterFinished or history limits, the ApprovalTask is deleted with it. To keep approval records for auditing:
- Export the
ApprovalTaskobjects, for example withkubectl get approvaltask <name> -n <namespace> -o yaml, before thePipelineRunis pruned, or - Lengthen the pruning retention for the namespaces that run approval pipelines.
Troubleshooting
- Approval task never appears: First run
kubectl get customruns -n <namespace>. If it lists noCustomRunfor the approval step, thePipelineRunhas not reached that step yet, for example because a task that runs before it is still running or has failed; check thePipelineRunstatus. If theCustomRunexists butkubectl get approvaltasks.openshift-pipelines.org -n <namespace>lists noApprovalTaskwith the same name, ask a cluster administrator to confirm that theManualApprovalGateCR isREADY(kubectl get manualapprovalgateshowsTruein theREADYcolumn). The CR is cluster-scoped, and the roles shipped with the Operator do not let pipeline authors read it. Without the controller,CustomRunobjects remain pending. - Approvers lack permissions: If the API server answers an approver's
kubectl patchwithForbidden, grant themget,list,update, andpatchaccess toapprovaltasks.openshift-pipelines.orgin the relevant namespace. A denial by the admission webhook withUser does not exist in the approval listorUser can only update their own approval inputis not fixed by RBAC: check that the approver entry uses the identifier described in User and group identifiers, and that the patch changes only the approver's own entry. - Pipeline ended before approval finished: Set both
PipelineRun.spec.timeouts.pipelineandPipelineRun.spec.timeouts.tasksto cover the expected approval window, and ensure the approvaltimeoutis realistic. Otherwise the run may time out even if approvers have not responded. - Stuck in pending even after approvals: Compare
status.approvalsReceivedwithstatus.approvalsRequiredinkubectl get approvaltask <name> -n <namespace> -o yaml. Approvals are counted per distinct user name: a user who is a user approver and a member of an approver group counts once. Once a user's approval in one of the two roles is recorded instatus.approversResponse, the webhook denies that user's approval in the other role withUser has already approved. A group member's approval counts only while the group'sinputisapprove. Collect the missing approvals from other approvers.
User and group identifiers
Manual Approval Gate relies on your platform's identity provider to match approver names. Always use the canonical identifiers exposed by the provider rather than UI display names. For example, on Alauda Container Platform:
For local users, use the USERNAME column (such as admin) when adding user approvers. For a user from an LDAP or OIDC connector, run kubectl auth whoami as that user and use the Username it prints.
For groups created in the console, use the NAME column (such as g-v9mfs), not the display name, when referencing group approvers (for example, group:g-v9mfs). For a group from an LDAP or OIDC connector, run kubectl auth whoami as a member of the group and use the group name as it appears in Groups. Other platforms expose similar resources—consult the identity service documentation for the exact field names.
Learn More
- Deploying
Manual Approval Gateas an administrator - Manual Approval Gate upstream repository
- Promote Artifacts with Skopeo Copy — shows an approval gate in front of a registry-to-registry image copy