diff options
Diffstat (limited to 'doc/user/project/releases/release_evidence.md')
-rw-r--r-- | doc/user/project/releases/release_evidence.md | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/doc/user/project/releases/release_evidence.md b/doc/user/project/releases/release_evidence.md new file mode 100644 index 00000000000..3269bf8f44b --- /dev/null +++ b/doc/user/project/releases/release_evidence.md @@ -0,0 +1,140 @@ +--- +stage: Govern +group: Compliance +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 +--- + +# Release evidence **(FREE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.6. + +Each time a release is created, GitLab takes a snapshot of data that's related to it. +This data is saved in a JSON file and called *release evidence*. The feature +includes test artifacts and linked milestones to facilitate +internal processes, like external audits. + +To access the release evidence, on the Releases page, select the link to the JSON file that's listed +under the **Evidence collection** heading. + +You can also [use the API](../../../api/releases/index.md#collect-release-evidence) to +generate release evidence for an existing release. Because of this, each release +can have multiple release evidence snapshots. You can view the release evidence and +its details on the Releases page. + +When the issue tracker is disabled, release evidence [can't be downloaded](https://gitlab.com/gitlab-org/gitlab/-/issues/208397). + +Here is an example of a release evidence object: + +```json +{ + "release": { + "id": 5, + "tag_name": "v4.0", + "name": "New release", + "project": { + "id": 20, + "name": "Project name", + "created_at": "2019-04-14T11:12:13.940Z", + "description": "Project description" + }, + "created_at": "2019-06-28 13:23:40 UTC", + "description": "Release description", + "milestones": [ + { + "id": 11, + "title": "v4.0-rc1", + "state": "closed", + "due_date": "2019-05-12 12:00:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [ + { + "id": 82, + "title": "The top-right popup is broken", + "author_name": "John Doe", + "author_email": "john@doe.com", + "state": "closed", + "due_date": "2019-05-10 12:00:00 UTC" + }, + { + "id": 89, + "title": "The title of this page is misleading", + "author_name": "Jane Smith", + "author_email": "jane@smith.com", + "state": "closed", + "due_date": "nil" + } + ] + }, + { + "id": 12, + "title": "v4.0-rc2", + "state": "closed", + "due_date": "2019-05-30 18:30:00 UTC", + "created_at": "2019-04-17 15:45:12 UTC", + "issues": [] + } + ], + "report_artifacts": [ + { + "url":"https://gitlab.example.com/root/project-name/-/jobs/111/artifacts/download" + } + ] + } +} +``` + +## Collect release evidence **(PREMIUM SELF)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/199065) in GitLab 12.10. + +When a release is created, release evidence is automatically collected. To initiate evidence collection any other time, use an [API call](../../../api/releases/index.md#collect-release-evidence). You can collect release evidence multiple times for one release. + +Evidence collection snapshots are visible on the Releases page, along with the timestamp the evidence was collected. + +## Include report artifacts as release evidence **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in GitLab 13.2. + +When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence. + +Although job artifacts normally expire, artifacts included in release evidence do not expire. + +To enable job artifact collection you must specify both: + +1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths) +1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports) + +```yaml +ruby: + script: + - gem install bundler + - bundle install + - bundle exec rspec --format progress --format RspecJunitFormatter --out rspec.xml + artifacts: + paths: + - rspec.xml + reports: + junit: rspec.xml +``` + +If the pipeline ran successfully, when you create your release, the `rspec.xml` file is saved as +release evidence. + +If you [schedule release evidence collection](#schedule-release-evidence-collection), +some artifacts may already be expired by the time of evidence collection. To avoid this you can use +the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) +keyword. For more information, see [issue 222351](https://gitlab.com/gitlab-org/gitlab/-/issues/222351). + +## Schedule release evidence collection + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/23697) in GitLab 12.8. + +In the API: + +- If you specify a future `released_at` date, the release becomes an **Upcoming release** + and the evidence is collected on the date of the release. You cannot collect + release evidence before then. +- If you specify a past `released_at` date, the release becomes an **Historical + release** and no evidence is collected. +- If you do not specify a `released_at` date, release evidence is collected on the + date the release is created. |