### Problem to solve <!-- What problem do we solve? --> During an audit, release metadata at the time of deployment (indicated by release end date) may be required to show what the release contained at time of deployment. We need to be able to support these requests in GitLab Releases. In https://gitlab.com/gitlab-org/gitlab/issues/26019, we established a snapshot for release metadata when a release entry was created. This issue will expand the release metadata snapshot to include a snapshot of a release's metadata when a release has ended. ### Intended users <!-- Who will use this feature? If known, include any of the following: types of users (e.g. Developer), personas, or specific company roles (e.g. Release Manager). It's okay to write "Unknown" and fill this field in later. * [Parker (Product Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#parker-product-manager) * [Delaney (Development Team Lead)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) * [Sasha (Software Developer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer) * [Presley (Product Designer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#presley-product-designer) * [Devon (DevOps Engineer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#devon-devops-engineer) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) * [Sam (Security Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sam-security-analyst) * [Dana (Data Analyst)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#dana-data-analyst) Personas are described at https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/ --> * Release Managers * Compliance and security teams ### Further details <!-- Include use cases, benefits, and/or goals (contributes to our vision?) --> From the snapshot issue at time of release end date: #### Upcoming Releases ##### Current Form An **Upcoming Release** is defined as a having a `released_at` set to a future point in time, at present this can be achieved only by an API call. An upcoming Release is defined via the `Release#upcoming_release?` method. ```ruby def upcoming_release? released_at.present? && released_at > Time.zone.now end ``` **TODO** - The definition of **Upcoming Release** should be added to the documentation. The current (incorrect) behavior for Evidence is that it is collected at the time of Release creation API call, for Upcoming Releases. #### Historical Releases It is presently possible to create a release with a historical `released_at` date. There may be valid reasons for this, but if this is done, then the Evidence is created as of the current time, which is probably incorrect. Evidence creation on Historical Releases is invalid and should be prevented. We may also consider marking Releases as **Historical Release** if they were created with a historical date (with a new column). The non-collection of creating Evidence, can be handled in this issue. #### Release and Evidence creation - Future form When a Release is created, determine if it is a **Release**, an **Upcoming Release** or a **Historical Release**. Passing the `released_at` field to the API is the deciding factor. The existing `after_commit` hook on Release will be removed, and instead the `CreateEvidenceWorker` call will be made in the API controller, after the Release object is successfully created. ```ruby after_commit :create_evidence!, on: :create, unless: :importing? ``` https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/releases.rb#L68-70 Current Release If the `released_at` field is not passed, it is defaulted to the current timestamp and the Evidence is created. The `CreateEvidenceWorker` will be scheduled as `perform_async`. Upcoming Release If a future `released_at` timestamp is provided via the API, the `CreateEvidenceWorker` will be scheduled for the future timestamp using the [Sidekiq Scheduled Jobs feature](https://github.com/mperham/sidekiq/wiki/Scheduled-Jobs), noting that it may not run exactly at the provided `released_at` timestamp. We may consider adding a 'Release Evidence will be collected at dttm' message to the Release page. Historical Release If the `released_at` timestamp is provided and is in the past, an Evidence object will not be provided for this release. ### Proposal <!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey --> * A snapshot of the release JSON and its SHA256 for the current source code associated with the tag. The content will include details of the release, the associated milestones, the project, and related issue details. Here's is the the release 12.6 JSON: ```json { "release": { "id": 5, "tag": "v4.0", "name": "New release", "project_id": 45, "project_name": "Project name", "released_at": "2019-06-28 13:23:40 UTC", "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": [] } ] } } ``` * A link to the external location of the \*.exe or installation file of the build/release: (the link itself is not strong enough to be evidence, but can help find it easily during in audit) `"links":[ { "id":3, "name":"hoge", "url":"https://google.com", "external":true }` * The source code link will download the source code associated with the tag. If a release gets updated with a new tag, the source code will be downloaded against this new tag. ### Permissions and Security <!-- What permissions are required to perform the described actions? Are they consistent with the existing permissions as documented for users, groups, and projects as appropriate? Is the proposed behavior consistent between the UI, API, and other access methods (e.g. email replies)?--> * Permissions to view the release evidence should be inherited from release data - meaning only those with access to the data within release evidence can see the data * In https://gitlab.com/gitlab-org/gitlab/issues/34402, we should not permit unauthenticated users to access milestone data * Editing of release evidence snapshot should not be permitted * Nobody is able to download the evidence who does not have access to all of the data that is collected there ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html Add all known Documentation Requirements here, per https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements If this feature requires changing permissions, this document https://docs.gitlab.com/ee/user/permissions.html must be updated accordingly. --> * [Release Evidence Docs](https://docs.gitlab.com/ee/user/project/releases/index.html#release-evidence) * [Release Permissions](https://docs.gitlab.com/ee/user/permissions.html#releases-permissions) ### What does success look like, and how can we measure that? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> * With the availability to see a snapshot at time of deployment, we should expect to see and increase in MAU of releases ### Links / references * [Related Snapshot Issue](https://gitlab.com/gitlab-org/gitlab/issues/26019)