Skip to content

Manual approve/reject action for deployment jobs

Previously titled: Manual approval action on the pipeline

Problem to solve

#15819 (closed) 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 (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 (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 (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

Further details

Spinnaker already supports this functionality
image
Codefresh.io support this functionality
image

The gitlab.yml file

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
  - master

Proposal

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
image
image
Pending Manual Job on Environments page
Manual job is not visible on environment page, even though it shows on pipeline list as skipped
image
image

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

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

Expand

This user flow is outdated, and refers to a previous design iteration


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

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

Documentation

Testing

What does success look like, and how can we measure that?

What is the type of buyer?

Links / references

Edited by Daniel Fosco