> Previously titled: **Manual approval action on the pipeline** ### Problem to solve <!-- What problem do we solve? --> https://gitlab.com/gitlab-org/gitlab/issues/15819 explains how to implement manual approvals from the `gitlab-ci.yml` file but there is no visual representation on the UI. The goal of this issue is to enable users with the right permissions to approve or reject manual jobs from the environments page, with the option to leave annotations. The main use case for this would be to improve the approval workflow for deployments, production or otherwise. ### Intended users **[Software Developer](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#sasha-software-developer) (Requester)** As a software developer, I want my code to be approved to go into production quickly, so I can move on to my next tasks **[Release Manager](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#rachel-release-manager) (Approver)** As a release manager, I want to make sure every deployment that is approved to go into production is in order, so I can reduce risk to our system's reliability **[Development Team Lead](https://about.gitlab.com/handbook/marketing/strategic-marketing/roles-personas/#delaney-development-team-lead) (Approver)** As a team lead, I want to approve my developers' code to go into production quickly, without introducing unnecessary risks, so we can deliver value to customers faster <!-- 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/ --> ### Further details <!-- Include use cases, benefits, and/or goals (contributes to our vision?) --> | Spinnaker already supports this functionality | | ------ | |  | | Codefresh.io support this functionality | | ------ | |  | The gitlab.yml file ```yaml deploy_prod: stage: deploy script: - echo "Deploy to production server" environment: name: production url: https://example.com when: manual only: - master ``` ### Proposal <!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey --> For every stage that the `gitlab-ci.yml` file defines that approvals are required, the pipeline execution of that run should pause before entering a stage that uses the environment. On the **environments page**, and option would be added to approve/deny the manual job that targets that environment, only available to people in that access list. Users configured as approvers must review and approve or reject the deployment. If you have multiple runs executing simultaneously, each one must be approved or rejected independently. This action must be recorded in the audit log. |Action| Details| |--|--| |Approval action | `approve/deny`| |The user | `username`| |Environment |`<Environment name>`| |Time| `timestamp`| |Stage|`pipeline stage`| ### What this currently looks like | Pending Manual Job on Pipeline Graph and Job Page | | ------ | |  | |  | | Pending Manual Job on Environments page | | ------ | | Manual job is not visible on environment page, even though it shows on pipeline list as `skipped` | |  | |  | ### What we are currently missing | Feature | Part of MVP | |------|------| | Approval/Rejection interface | Yes | | Audit Log | Yes | | Add approval/rejection message (to be added as an MR comment) | No | | Notifications that your approval is required (TODO, email, slack...) | No | **Notes** - If a protected environment has has a “Deploy to” dropdown as one of its [action buttons](https://gitlab.com/gitlab-org/gitlab/-/issues/335228), then it should be disabled. - If a user rejects the manual job, we can either force it to fail, or create a new job status of `rejected`. [From the docs](https://docs.gitlab.com/ee/api/jobs.html), this is what we currently support: | Attribute | Type | Required | Description | |-----------|------|----------|-------------| | scope | string or array of strings | no | Scope of jobs to show. Either one of or an array of the following: created, pending, running, failed, success, canceled, skipped, or manual. All jobs are returned if scope is not provided. | ### UI Proposal 👉 **See Mockups in [Design Tab](https://gitlab.com/gitlab-org/gitlab/-/issues/35412/designs/1.0_env__approval.png)** #### Interfaces Breakdown | Interface | Part of MVC | | ------ | ------ | Approval UI - Environments page | Yes | | Approval UI - Deployments List | No | | Approval UI - Single Job Page | No | _This is a tentative breakdown of this issue into smaller parts based on the interfaces designed. This is just an estimation_ #### User Flow <details> <summary> Expand </summary> **This user flow is outdated, and refers to a previous design iteration** ```mermaid %%{init: {'theme': 'base', 'themeVariables': { 'nodeBorder' : '#004990', 'mainBkg' : '#c9d7e4', 'background' : '#fcfcfc', 'nodeTextColor' : '#274059', 'fontFamily': 'arial', 'fontSize': '20px'}}}%% graph TD %%nodes 0[Developer] 1[Merge Request is created] 2([Manual Job]) 3["Job approver is notified (via Slack / Email / GitLab To-Do)"] 3.1["Job listed in MR page as “waiting to be allowed / denied”"] 3.2["Job pill in pipeline graph with Allow / Deny actions"] 3.3{ } X0{ } X1[Output is saved to audit log] X2[Output and comment are added to MR page] X3[Developer is notified] X4{ } 4A[Allow job] 5A["Job runs"] 4B[Deny job] 5B["Job does not run"] %%connections 0 --> 1 1 -->|pipeline runs and gets to| 2 2 -->|Job waiting to be allowed or denied| 3 3 --> 3.1 3.1 -->|This entry links to| 3.2 3.2 ---|Job Approver can| 3.3 3.3 --> 4A 4A --- X0 X4 --> 5A 3.3 --> 4B 4B --- X0 X0 --> X1 --> X2 --> X3 --> X4 X4 --> 5B ``` </details> #### Possible Future Iterations - Enable turning comments mandatory for allow/deny by adding a setting to environment YAML - Add rich-markdown editor capabilities to comment box (@mentions, smart links, etc) ### 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)?--> ### 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. --> ### Testing <!-- What risks does this change pose? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? See the test engineering process for further help: https://about.gitlab.com/handbook/engineering/quality/test-engineering/ --> ### 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. --> ### What is the type of buyer? <!-- Which leads to: in which enterprise tier should this feature go? See https://about.gitlab.com/handbook/product/pricing/#four-tiers --> ### Links / references * https://docs.microsoft.com/en-us/azure/devops/pipelines/process/approvals?view=azure-devops * https://codefresh.io/continuous-deployment/manual-approval/