Skip to content

Commit 2174ae8

Browse files
PuneetPunamiyambpavan
PuneetPunamiya
authored and
mbpavan
committed
docs: add ApprovalTask guide and correct CLI reference
Add complete ApprovalTask documentation and CLI docs to match the actual tkn-approvaltask implementation. Signed-off-by: PuneetPunamiya <[email protected]>
1 parent 7e06933 commit 2174ae8

File tree

2 files changed

+416
-0
lines changed

2 files changed

+416
-0
lines changed

‎docs/APPROVAL_TASK_GUIDE.md

Lines changed: 290 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
# ApprovalTask Guide
2+
3+
This guide provides comprehensive documentation for using ApprovalTask in your Tekton Pipelines to add manual approval points.
4+
5+
## Table of Contents
6+
7+
- [Overview](#overview)
8+
- [ApprovalTask Structure](#approvaltask-structure)
9+
- [Basic Examples](#basic-examples)
10+
- [Advanced Examples](#advanced-examples)
11+
- [Status Fields](#status-fields)
12+
13+
## Overview
14+
15+
ApprovalTask is a Kubernetes Custom Resource that allows you to add manual approval gates in your CI/CD pipelines. When a pipeline reaches an ApprovalTask, it pauses execution until the required number of approvals are received from designated approvers.
16+
17+
## ApprovalTask Structure
18+
19+
### Complete ApprovalTask Example
20+
21+
```yaml
22+
apiVersion: openshift-pipelines.org/v1alpha1
23+
kind: ApprovalTask
24+
metadata:
25+
name: deployment-approval
26+
namespace: my-project
27+
spec:
28+
approvers:
29+
- name: alice
30+
type: User
31+
input: pending
32+
message: ""
33+
- name: bob
34+
type: User
35+
input: pending
36+
message: ""
37+
- name: dev-team
38+
type: Group
39+
input: pending
40+
message: ""
41+
users:
42+
- name: charlie
43+
input: pending
44+
- name: diana
45+
input: pending
46+
numberOfApprovalsRequired: 2
47+
description: "Approve deployment to production environment"
48+
status:
49+
state: pending
50+
approvers:
51+
- alice
52+
- bob
53+
- dev-team
54+
approvalsRequired: 2
55+
approvalsReceived: 0
56+
approversResponse: []
57+
startTime: "2024-01-15T10:30:00Z"
58+
```
59+
60+
### Spec Fields
61+
62+
| Field | Type | Required | Description |
63+
|-------|------|----------|-------------|
64+
| `approvers` | []ApproverDetails | Yes | List of users/groups who can approve |
65+
| `numberOfApprovalsRequired` | int | Yes | Number of approvals needed |
66+
| `description` | string | No | Description of what needs approval |
67+
68+
### ApproverDetails Fields
69+
70+
| Field | Type | Required | Description |
71+
|-------|------|----------|-------------|
72+
| `name` | string | Yes | Username or group name |
73+
| `type` | string | Yes | "User" or "Group" |
74+
| `input` | string | Yes | Current state: "pending", "approve", "reject" |
75+
| `message` | string | No | Message from approver |
76+
| `users` | []UserDetails | No | Group members (for Group type) |
77+
78+
### Status Fields
79+
80+
| Field | Type | Description |
81+
|-------|------|-------------|
82+
| `state` | string | Overall state: "pending", "approved", "rejected" |
83+
| `approvers` | []string | List of approver names |
84+
| `approvalsRequired` | int | Number of approvals required |
85+
| `approvalsReceived` | int | Number of approvals received so far |
86+
| `approversResponse` | []ApproverState | Detailed response from each approver |
87+
| `startTime` | *metav1.Time | When the approval task started |
88+
89+
## Basic Examples
90+
91+
### 1. Simple User Approval
92+
93+
```yaml
94+
apiVersion: openshift-pipelines.org/v1alpha1
95+
kind: ApprovalTask
96+
metadata:
97+
name: simple-approval
98+
namespace: default
99+
spec:
100+
approvers:
101+
- name: alice
102+
type: User
103+
input: pending
104+
numberOfApprovalsRequired: 1
105+
description: "Simple approval for feature deployment"
106+
```
107+
108+
### 2. Multiple User Approval
109+
110+
```yaml
111+
apiVersion: openshift-pipelines.org/v1alpha1
112+
kind: ApprovalTask
113+
metadata:
114+
name: multi-user-approval
115+
namespace: default
116+
spec:
117+
approvers:
118+
- name: alice
119+
type: User
120+
input: pending
121+
- name: bob
122+
type: User
123+
input: pending
124+
- name: charlie
125+
type: User
126+
input: pending
127+
numberOfApprovalsRequired: 2
128+
description: "Requires 2 out of 3 approvals for production deployment"
129+
```
130+
131+
### 3. Group-Based Approval
132+
133+
```yaml
134+
apiVersion: openshift-pipelines.org/v1alpha1
135+
kind: ApprovalTask
136+
metadata:
137+
name: group-approval
138+
namespace: default
139+
spec:
140+
approvers:
141+
- name: dev-team
142+
type: Group
143+
input: pending
144+
users:
145+
- name: alice
146+
input: pending
147+
- name: bob
148+
input: pending
149+
- name: charlie
150+
input: pending
151+
numberOfApprovalsRequired: 1
152+
description: "Any member of dev-team can approve"
153+
```
154+
155+
## Advanced Examples
156+
157+
### 1. Mixed User and Group Approval
158+
159+
```yaml
160+
apiVersion: openshift-pipelines.org/v1alpha1
161+
kind: ApprovalTask
162+
metadata:
163+
name: mixed-approval
164+
namespace: default
165+
spec:
166+
approvers:
167+
- name: tech-lead
168+
type: User
169+
input: pending
170+
- name: qa-team
171+
type: Group
172+
input: pending
173+
users:
174+
- name: tester1
175+
input: pending
176+
- name: tester2
177+
input: pending
178+
- name: security-team
179+
type: Group
180+
input: pending
181+
users:
182+
- name: security-lead
183+
input: pending
184+
- name: security-analyst
185+
input: pending
186+
numberOfApprovalsRequired: 3
187+
description: "Requires tech lead + QA team member + security team member"
188+
```
189+
190+
### 2. Using in Pipeline
191+
192+
```yaml
193+
apiVersion: tekton.dev/v1beta1
194+
kind: Pipeline
195+
metadata:
196+
name: deployment-pipeline
197+
spec:
198+
tasks:
199+
- name: build
200+
taskRef:
201+
name: build-task
202+
- name: test
203+
taskRef:
204+
name: test-task
205+
runAfter: [build]
206+
- name: approval-gate
207+
taskRef:
208+
apiVersion: openshift-pipelines.org/v1alpha1
209+
kind: ApprovalTask
210+
params:
211+
- name: approvers
212+
value:
213+
- alice
214+
- bob
215+
- group:security-team
216+
- name: numberOfApprovalsRequired
217+
value: "2"
218+
- name: description
219+
value: "Approve deployment to production"
220+
runAfter: [test]
221+
- name: deploy
222+
taskRef:
223+
name: deploy-task
224+
runAfter: [approval-gate]
225+
```
226+
227+
## Status Fields
228+
229+
The ApprovalTask status provides detailed information about the approval process:
230+
231+
### Progress Tracking
232+
233+
```yaml
234+
status:
235+
state: pending
236+
approvalsRequired: 3 # Total approvals needed
237+
approvalsReceived: 1 # Current approvals count
238+
approvers:
239+
- alice
240+
- bob
241+
- security-team
242+
approversResponse:
243+
- name: alice
244+
type: User
245+
response: approved
246+
message: "LGTM for production deployment"
247+
- name: bob
248+
type: User
249+
response: pending
250+
- name: security-team
251+
type: Group
252+
response: pending
253+
groupMembers: []
254+
```
255+
256+
### Approved State
257+
258+
```yaml
259+
status:
260+
state: approved
261+
approvalsRequired: 2
262+
approvalsReceived: 2
263+
approversResponse:
264+
- name: alice
265+
type: User
266+
response: approved
267+
message: "Code looks good"
268+
- name: security-team
269+
type: Group
270+
response: approved
271+
message: "Security review passed"
272+
groupMembers:
273+
- name: security-lead
274+
response: approved
275+
message: "No security issues found"
276+
```
277+
278+
### Rejected State
279+
280+
```yaml
281+
status:
282+
state: rejected
283+
approvalsRequired: 2
284+
approvalsReceived: 0
285+
approversResponse:
286+
- name: alice
287+
type: User
288+
response: rejected
289+
message: "Found critical bugs in the code"
290+
```

0 commit comments

Comments
 (0)