Manual Approval Gate for Tekton Pipelines

Feature 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 ApprovalTask status 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/PipelineRun objects in the target namespace.
  • Approvers can patch approvaltasks.openshift-pipelines.org resources (typically via kubectl) in the target namespace.
  • The jq CLI, used to read ApprovalTask fields in the steps below.

Steps

1. Declare the approval step in a pipeline

apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: deploy-with-approval
spec:
  tasks:
    - name: build
      taskRef:
        name: build-bundle     # Placeholder Task; replace with your build logic
    - name: wait-for-approval
      runAfter:
        - build
      taskRef:
        apiVersion: openshift-pipelines.org/v1alpha1
        kind: ApprovalTask
      timeout: "24h"
      params:
        - name: approvers
          value:
            - alice
            - group:release-managers
        - name: numberOfApprovalsRequired
          value: "1"
        - name: description
          value: "Approve promotion into production"
    - name: deploy
      runAfter:
        - wait-for-approval
      taskRef:
        name: deploy-prod     # Placeholder Task; replace with your deployment logic

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

PropertyValue
TypeString containing an integer, for example "2"
Default"1" when the parameter is omitted
ValidationMust be an integer greater than 0. Otherwise the CustomRun fails with a validation error.
Upper boundNone. The value is not compared with the number of entries in approvers.

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.

WARNING

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:

apiVersion: tekton.dev/v1
kind: PipelineRun
metadata:
  name: deploy-with-approval-run
spec:
  pipelineRef:
    name: deploy-with-approval
  timeouts:
    pipeline: 72h
    tasks: 72h
kubectl create -f deploy-with-approval-run.yaml

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

$ kubectl get approvaltasks.openshift-pipelines.org

NAME                                         AGE
deploy-with-approval-run-wait-for-approval   4m16s
$ kubectl describe approvaltask deploy-with-approval-run-wait-for-approval
Name:         deploy-with-approval-run-wait-for-approval
Status:
  Approvals Required:  1
  Approvers:
    alice
    release-managers
  State:  pending
Events:   <none>

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 as pending, approved, or rejected.
  • 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:

$ kubectl get approvaltask deploy-with-approval-run-wait-for-approval -o json | jq '.spec.approvers'
[
  {
    "input": "pending",
    "name": "alice",
    "type": "User"
  },
  {
    "input": "pending",
    "name": "release-managers",
    "type": "Group"
  }
]

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:

kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as alice \
    -p='[
      {"op":"replace","path":"/spec/approvers/0/input","value":"approve"},
      {"op":"replace","path":"/spec/approvers/0/message","value":"QA complete"}
    ]'

To reject as a user:

kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as alice \
    -p='[
      {"op":"replace","path":"/spec/approvers/0/input","value":"reject"},
      {"op":"replace","path":"/spec/approvers/0/message","value":"Found regression"}
    ]'

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:

kubectl delete pipelinerun deploy-with-approval-run

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:

spec:
  approvers:
  - name: alice
    type: User
    input: pending
  - name: release-managers
    type: Group
    input: pending
  numberOfApprovalsRequired: 2

The first group member creates the users array and sets the group's input to approve:

# First member (bob) from release-managers group approves
kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as bob \
    --as-group release-managers \
    -p='[
      {"op":"add","path":"/spec/approvers/1/users","value":[{"name":"bob","input":"approve"}]},
      {"op":"replace","path":"/spec/approvers/1/input","value":"approve"},
      {"op":"replace","path":"/spec/approvers/1/message","value":"Approved by bob"}
    ]'

Subsequent group members append to the existing users array and update the group's input:

# Second member (carol) from release-managers group also approves
kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as carol \
    --as-group release-managers \
    -p='[
      {"op":"add","path":"/spec/approvers/1/users/-","value":{"name":"carol","input":"approve"}},
      {"op":"replace","path":"/spec/approvers/1/input","value":"approve"},
      {"op":"replace","path":"/spec/approvers/1/message","value":"Approved by carol"}
    ]'

To reject as a group member:

# A member (david) from release-managers group rejects
kubectl patch approvaltask deploy-with-approval-run-wait-for-approval \
    --type='json' \
    --as david \
    --as-group release-managers \
    -p='[
      {"op":"add","path":"/spec/approvers/1/users/-","value":{"name":"david","input":"reject"}},
      {"op":"replace","path":"/spec/approvers/1/input","value":"reject"},
      {"op":"replace","path":"/spec/approvers/1/message","value":"Security concerns found"}
    ]'

After the bob and carol patches, check the group entry and status to see all members' responses:

$ kubectl get approvaltask deploy-with-approval-run-wait-for-approval -o json | jq '{spec: .spec.approvers[1], status: .status}'
{
  "spec": {
    "input": "approve",
    "message": "Approved by carol",
    "name": "release-managers",
    "type": "Group",
    "users": [
      {
        "input": "approve",
        "name": "bob"
      },
      {
        "input": "approve",
        "name": "carol"
      }
    ]
  },
  "status": {
    "approvalsReceived": 2,
    "approvalsRequired": 2,
    "approvers": [
      "alice",
      "release-managers"
    ],
    "approversResponse": [
      {
        "groupMembers": [
          {
            "name": "bob",
            "response": "approved"
          },
          {
            "name": "carol",
            "response": "approved"
          }
        ],
        "message": "Approved by carol",
        "name": "release-managers",
        "response": "approved",
        "type": "Group"
      }
    ],
    "startTime": "2025-11-18T14:07:48Z",
    "state": "approved"
  }
}

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 users array AND set the group's input (either approve or reject). Optionally, they can also set the group's message
  • The first group member creates the users array using path /spec/approvers/<index>/users with 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 users array has name and input, and may also have its own message. That message appears in the member's groupMembers entry in status.approversResponse; the entries in the output above have none because the patches set none
  • The group-level message field is optional and shared; it will be overwritten by subsequent responses if they provide a new message
  • Each group member approval increments approvalsReceived independently
  • Multiple members from the same group can approve, and each counts toward the required total
  • The status.approversResponse field 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 ApprovalTask as 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-managers sends the request as user bob in the release-managers group.

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 yaml shows each approval gate with state and quorum-related fields (the status.approvalsReceived field counts approvals and appears after the first approval).
  • PipelineRun status reflects the approval outcome: when approved, downstream tasks resume; when rejected, the PipelineRun fails (Succeeded is False, reason Failed). The approval step's CustomRun shows Approval Task denied, and status.approversResponse of the ApprovalTask shows who rejected it and their message.
  • Dispatch logs or kubectl get approvaltask -o yaml output provide the approval history for auditing. The ApprovalTask is deleted together with its PipelineRun; 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 ApprovalTask objects, for example with kubectl get approvaltask <name> -n <namespace> -o yaml, before the PipelineRun is 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 no CustomRun for the approval step, the PipelineRun has not reached that step yet, for example because a task that runs before it is still running or has failed; check the PipelineRun status. If the CustomRun exists but kubectl get approvaltasks.openshift-pipelines.org -n <namespace> lists no ApprovalTask with the same name, ask a cluster administrator to confirm that the ManualApprovalGate CR is READY (kubectl get manualapprovalgate shows True in the READY column). The CR is cluster-scoped, and the roles shipped with the Operator do not let pipeline authors read it. Without the controller, CustomRun objects remain pending.
  • Approvers lack permissions: If the API server answers an approver's kubectl patch with Forbidden, grant them get, list, update, and patch access to approvaltasks.openshift-pipelines.org in the relevant namespace. A denial by the admission webhook with User does not exist in the approval list or User can only update their own approval input is 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.pipeline and PipelineRun.spec.timeouts.tasks to cover the expected approval window, and ensure the approval timeout is realistic. Otherwise the run may time out even if approvers have not responded.
  • Stuck in pending even after approvals: Compare status.approvalsReceived with status.approvalsRequired in kubectl 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 in status.approversResponse, the webhook denies that user's approval in the other role with User has already approved. A group member's approval counts only while the group's input is approve. 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:

$ kubectl get users.auth.alauda.io
NAME                               TYPE    USERNAME   AGE
21232f297a57a5a743894a0e4a801fc3   local   admin      19d

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.

$ kubectl get groups.auth.alauda.io
NAME      DISPLAYNAME   CONNTYPE   CONNID   AGE
g-v9mfs   test-group    local      local    19d

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