1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
|
---
type: reference, howto
stage: Plan
group: Product Planning
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
---
# Requirements management **(ULTIMATE ALL)**
NOTE:
In 14.4, Requirements was moved under **Issues**.
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2703) in GitLab 12.10.
> - The ability to add and edit a requirement's long description [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224622) in GitLab 13.5.
> - [Moved under Issues](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/70748) in 14.4
With requirements, you can set criteria to check your products against. They can be based on users,
stakeholders, system, software, or anything else you find important to capture.
A requirement is an artifact in GitLab which describes the specific behavior of your product.
Requirements are long-lived and don't disappear unless manually cleared.
If an industry standard *requires* that your application has a certain feature or behavior, you can
[create a requirement](#create-a-requirement) to reflect this.
When a feature is no longer necessary, you can [archive the related requirement](#archive-a-requirement).
NOTE:
Requirements and [test cases](../../../ci/test_cases/index.md) are being
[migrated to work items](https://gitlab.com/groups/gitlab-org/-/epics/5171).
[Issue 323790](https://gitlab.com/gitlab-org/gitlab/-/issues/323790) proposes to link requirements to test cases.
For more information, see [Product Stage Direction - Plan](https://about.gitlab.com/direction/plan/).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [GitLab 12.10 Introduces Requirements Management](https://www.youtube.com/watch?v=uSS7oUNSEoU).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For a more in-depth walkthrough see [GitLab Requirements Traceability Walkthrough](https://youtu.be/VIiuTQYFVa0) (Feb 2021).
![requirements list view](img/requirements_list_v13_5.png)
## Create a requirement
A paginated list of requirements is available in each project, and there you
can create a new requirement.
Prerequisite:
- You must have at least the Reporter role.
To create a requirement:
1. In a project, go to **Plan > Requirements**.
1. Select **New requirement**.
1. Enter a title and description and select **Create requirement**.
![requirement create view](img/requirement_create_v13_5.png)
You can see the newly created requirement on the top of the list, with the requirements
list being sorted by creation date, in descending order.
## View a requirement
You can view a requirement from the list by selecting it.
![requirement view](img/requirement_view_v13_5.png)
To edit a requirement while viewing it, select the **Edit** icon (**{pencil}**)
next to the requirement title.
## Edit a requirement
> The ability to mark a requirement as Satisfied [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/218607) in GitLab 13.5.
You can edit a requirement from the requirements list page.
Prerequisite:
- You must have at least the Reporter role.
To edit a requirement:
1. From the requirements list, select the **Edit** icon (**{pencil}**).
1. Update the title and description in text input field. You can also mark a
requirement as satisfied in the edit form by using the checkbox **Satisfied**.
1. Select **Save changes**.
## Archive a requirement
You can archive an open requirement while
you're in the **Open** tab.
Prerequisite:
- You must have at least the Reporter role.
To archive a requirement, select **Archive** (**{archive}**).
As soon as a requirement is archived, it no longer appears in the **Open** tab.
## Reopen a requirement
You can view the list of archived requirements in the **Archived** tab.
Prerequisite:
- You must have at least the Reporter role.
![archived requirements list](img/requirements_archived_list_view_v13_1.png)
To reopen an archived requirement, select **Reopen**.
As soon as a requirement is reopened, it no longer appears in the **Archived** tab.
## Search for a requirement
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/212543) in GitLab 13.1.
> - Searching by status [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/224614) in GitLab 13.10.
You can search for a requirement from the requirements list page based on the following criteria:
- Title
- Author's username
- Status (satisfied, failed, or missing)
To search for a requirement:
1. In a project, go to **Plan > Requirements > List**.
1. Select the **Search or filter results** field. A dropdown list appears.
1. Select the requirement author or status from the dropdown list or enter plain text to search by requirement title.
1. Press <kbd>Enter</kbd> on your keyboard to filter the list.
You can also sort the requirements list by:
- Created date
- Updated date
## Allow requirements to be satisfied from a CI job
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in GitLab 13.1.
> - Ability to specify individual requirements and their statuses [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) in GitLab 13.2.
GitLab supports [requirements test reports](../../../ci/yaml/artifacts_reports.md#artifactsreportsrequirements) now.
You can add a job to your CI pipeline that, when triggered, marks all existing
requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)).
### Add the manual job to CI
To configure your CI to mark requirements as Satisfied when the manual job is
triggered, add the code below to your `.gitlab-ci.yml` file.
```yaml
requirements_confirmation:
when: manual
allow_failure: false
script:
- mkdir tmp
- echo "{\"*\":\"passed\"}" > tmp/requirements.json
artifacts:
reports:
requirements: tmp/requirements.json
```
This definition adds a manually-triggered (`when: manual`) job to the CI
pipeline. It's blocking (`allow_failure: false`), but it's up to you what
conditions you use for triggering the CI job. Also, you can use any existing CI job
to mark all requirements as satisfied, as long as the `requirements.json`
artifact is generated and uploaded by the CI job.
When you manually trigger this job, the `requirements.json` file containing
`{"*":"passed"}` is uploaded as an artifact to the server. On the server side,
the requirement report is checked for the "all passed" record
(`{"*":"passed"}`), and on success, it marks all existing open requirements as
Satisfied.
#### Specifying individual requirements
It is possible to specify individual requirements and their statuses.
If the following requirements exist:
- `REQ-1` (with IID `1`)
- `REQ-2` (with IID `2`)
- `REQ-3` (with IID `3`)
It is possible to specify that the first requirement passed, and the second failed.
Valid values are "passed" and "failed".
By omitting a requirement IID (in this case `REQ-3`'s IID `3`), no result is noted.
```yaml
requirements_confirmation:
when: manual
allow_failure: false
script:
- mkdir tmp
- echo "{\"1\":\"passed\", \"2\":\"failed\"}" > tmp/requirements.json
artifacts:
reports:
requirements: tmp/requirements.json
```
### Add the manual job to CI conditionally
To configure your CI to include the manual job only when there are some open
requirements, add a rule which checks `CI_HAS_OPEN_REQUIREMENTS` CI/CD variable.
```yaml
requirements_confirmation:
rules:
- if: "$CI_HAS_OPEN_REQUIREMENTS" == "true"
when: manual
- when: never
allow_failure: false
script:
- mkdir tmp
- echo "{\"*\":\"passed\"}" > tmp/requirements.json
artifacts:
reports:
requirements: tmp/requirements.json
```
## Import requirements from a CSV file
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246857) in GitLab 13.7.
You must have at least the Reporter role.
You can import requirements to a project by uploading a [CSV file](https://en.wikipedia.org/wiki/Comma-separated_values)
with the columns `title` and `description`.
After the import, the user uploading the CSV file is set as the author of the imported requirements.
### Import the file
Before you import your file:
- Consider importing a test file containing only a few requirements. There is no way to undo a large
import without using the GitLab API.
- Ensure your CSV file meets the [file format](#imported-csv-file-format) requirements.
To import requirements:
1. In a project, go to **Plan > Requirements**.
- For a project with requirements, in the
upper-right corner, select the import icon (**{import}**).
- For a project without requirements, in the middle of the page, select **Import CSV**.
1. Select the file and select **Import requirements**.
The file is processed in the background and a notification email is sent
to you after the import is complete.
### Imported CSV file format
When importing requirements from a CSV file, it must be formatted in a certain way:
- **Header row:** CSV files must include the following headers:
`title` and `description`. The headers are case insensitive.
- **Columns:** data from columns other than `title` and `description` is not imported.
- **Separators:** the column separator is automatically detected from the header row.
Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`).
The row separator can be either `CRLF` or `LF`.
- **Double-quote character:** the double-quote (`"`) character is used to quote fields,
enabling the use of the column separator in a field (see the third line in the
sample CSV data below). To insert a double-quote (`"`) in a quoted
field, use two double-quote characters in succession (`""`).
- **Data rows:** below the header row, succeeding rows must follow the same column
order. The title text is required, while the description is optional and can be left empty.
Sample CSV data:
```plaintext
title,description
My Requirement Title,My Requirement Description
Another Title,"A description, with a comma"
"One More Title","One More Description"
```
### File size
The limit depends on the configuration value of Max Attachment Size for the GitLab instance.
For GitLab.com, it is set to 10 MB.
## Export requirements to a CSV file
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290813) in GitLab 13.8.
> - Revised CSV column headers [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/299247) in GitLab 13.9.
> - Ability to select which fields to export [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/290823) in GitLab 13.9.
You can export GitLab requirements to a
[CSV file](https://en.wikipedia.org/wiki/Comma-separated_values) sent to your default notification
email as an attachment.
By exporting requirements, you and your team can import them into another tool or share them with
your customers. Exporting requirements can aid collaboration with higher-level systems, as well as
audit and regulatory compliance tasks.
Prerequisite:
- You must have at least the Reporter role.
To export requirements:
1. In a project, go to **Plan > Requirements**.
1. In the upper-right corner, select **Export as CSV** (**{export}**).
A confirmation modal appears.
1. Under **Advanced export options**, select which fields to export.
All fields are selected by default. To exclude a field from being exported, clear the checkbox next to it.
1. Select **Export requirements**. The exported CSV file is sent to the email address associated with your user.
### Exported CSV file format
<!-- vale gitlab.Spelling = NO -->
You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel,
OpenOffice Calc, or Google Sheets.
<!-- vale gitlab.Spelling = YES -->
The exported CSV file contains the following headers:
- In GitLab 13.8:
- Requirement ID
- Title
- Description
- Author Username
- Latest Test Report State
- Latest Test Report Created At (UTC)
- In GitLab 13.9 and later:
- Requirement ID
- Title
- Description
- Author
- Author Username
- Created At (UTC)
- State
- State Updated At (UTC)
|