Skip to content

GitLab

Requirements Management (ULTIMATE)

Introduced in GitLab Ultimate 12.10.

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.

For an overview, see GitLab 12.10 Introduces Requirements Management.

requirements list view

Create a requirement

A paginated list of requirements is available in each project, and there you can create a new requirement.

To create a requirement:

  1. From your project page, go to {requirements} Requirements.
  2. Click New requirement.
  3. Enter a descriptive title and click Create requirement.

You will see the newly created requirement on the top of the list, as the requirements list is sorted by creation date in descending order.

Edit a requirement

You can edit a requirement (if you have the necessary privileges) from the requirements list page.

To edit a requirement:

  1. From the requirements list, click Edit ({pencil}).
  2. Update the title in text input field.
  3. Click Save changes.

Archive a requirement

You can archive an open requirement (if you have the necessary privileges) while you're in the Open tab.

To archive a requirement, click 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.

archived requirements list

To reopen an archived requirement, click Reopen.

As soon as a requirement is reopened, it no longer appears in the Archived tab.

Search for a requirement

Introduced in GitLab Ultimate 13.1.

You can search for a requirement from the requirements list page based on the following criteria:

  • Requirement title
  • Author's username

To search for a requirement:

  1. In a project, go to {requirements} Requirements > List.
  2. Click the Search or filter results field. A dropdown menu appears.
  3. Select the requirement author from the dropdown or enter plain text to search by requirement title.
  4. Press Enter on your keyboard to filter the list.

You can also sort the requirements list by:

  • Created date
  • Last updated

Allow requirements to be satisfied from a CI job

GitLab supports requirements test reports now. You can add a job to your CI pipeline that, when triggered, marks all existing requirements as Satisfied.

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.

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.

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 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