doc/user/project/requirements/_index.md
{{< details >}}
{{< /details >}}
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 to reflect this. When a feature is no longer necessary, you can archive the related requirement.
<i class="fa-youtube-play" aria-hidden="true"></i> For an overview, see Requirements Management.
<!-- Video published on 2020-04-09 --><i class="fa-youtube-play" aria-hidden="true"></i> For a more in-depth walkthrough see GitLab Requirements Traceability Walkthrough.
<!-- Video published on 2020-02-12 -->{{< history >}}
{{< /history >}}
A paginated list of requirements is available in each project, and there you can create a new requirement.
Prerequisites:
To create a requirement:
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.
You can view a requirement from the list by selecting it.
To edit a requirement while viewing it, select the Edit icon ({{< icon name="pencil" >}}) next to the requirement title.
{{< history >}}
{{< /history >}}
You can edit a requirement from the requirements list page.
Prerequisites:
To edit a requirement:
{{< history >}}
{{< /history >}}
You can archive an open requirement while you're in the Open tab.
Prerequisites:
To archive a requirement, select Archive ({{< icon name="archive" >}}).
As soon as a requirement is archived, it no longer appears in the Open tab.
{{< history >}}
{{< /history >}}
You can view the list of archived requirements in the Archived tab.
Prerequisites:
To reopen an archived requirement, select Reopen.
As soon as a requirement is reopened, it no longer appears in the Archived tab.
You can search for a requirement from the requirements list page based on the following criteria:
To search for a requirement:
You can also sort the requirements list by:
GitLab supports requirements test reports 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).
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.
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.
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.
requirements_confirmation:
when: manual
allow_failure: false
script:
- mkdir tmp
- echo "{\"1\":\"passed\", \"2\":\"failed\"}" > tmp/requirements.json
artifacts:
reports:
requirements: tmp/requirements.json
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.
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
Because requirements and test cases are being
migrated to work items, if you have enabled work items
in a project, you must replace requirements in the previous config with requirements_v2:
requirements_v2: tmp/requirements.json
{{< history >}}
{{< /history >}}
You must have the Planner, Reporter, Developer, Maintainer, or Owner role.
You can import requirements to a project by uploading a CSV file
with the columns title and description.
After the import, the user uploading the CSV file is set as the author of the imported requirements.
Before you import your file:
To import requirements:
The file is processed in the background and a notification email is sent to you after the import is complete.
When importing requirements from a CSV file, it must be formatted in a certain way:
title and description. The headers are case-insensitive.title and description is not imported.,), semicolons (;), and tabs (\t).
The row separator can be either CRLF or LF.") 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 ("").Sample CSV data:
title,description
My Requirement Title,My Requirement Description
Another Title,"A description, with a comma"
"One More Title","One More Description"
The limit depends on the configuration value of Max Attachment Size for the GitLab instance.
For GitLab.com, it is set to 10 MB.
{{< history >}}
{{< /history >}}
You can export GitLab requirements to a CSV file 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.
Prerequisites:
To export requirements:
In a project, go to Plan > Requirements.
In the upper-right corner, select the vertical ellipsis ({{< icon name="ellipsis_v" >}}), then select Export as CSV ({{< icon name="export" >}}).
A confirmation dialog appears.
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.
Select Export requirements. The exported CSV file is sent to the email address associated with your user.
You can preview the exported CSV file in a spreadsheet editor, such as Microsoft Excel, OpenOffice Calc, or Google Sheets.
<!-- vale gitlab_base.Spelling = YES -->The exported CSV file contains the following headers: