gitlab-org--gitlab-foss/doc/ci/environments/deployment_approvals.md

stage	group	info	description
Release	Release	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	Require approvals prior to deploying to a Protected Environment

Deployment approvals (PREMIUM)

• Introduced in GitLab 14.7 with a flag named deployment_approvals. Disabled by default.
• Feature flag removed in GitLab 14.8.

WARNING: This feature is in a Beta stage and subject to change without prior notice.

It may be useful to require additional approvals before deploying to certain protected environments (for example, production). This pre-deployment approval requirement is useful to accommodate testing, security, or compliance processes that must happen before each deployment.

When a protected environment requires one or more approvals, all deployments to that environment become blocked and wait for the required approvals from the Allowed to Deploy list before running.

NOTE: See the epic for planned features.

Requirements

• Basic knowledge of GitLab Environments and Deployments.
• Basic knowledge of Protected Environments.

Configure deployment approvals for a project

To configure deployment approvals for a project:

1. Create a deployment job.
2. Require approvals for a protected environment.

Create a deployment job

Create a deployment job in the .gitlab-ci.yaml file of the desired project. The job does not need to be manual (when: manual).

Example:

stages:
  - deploy

production:
  stage: deploy
  script:
    - 'echo "Deploying to ${CI_ENVIRONMENT_NAME}"'
  environment:
    name: ${CI_JOB_NAME}

Require approvals for a protected environment

NOTE: At this time, it is not possible to require approvals for an existing protected environment. The workaround is to unprotect the environment and configure approvals when re-protecting the environment.

There are two ways to configure approvals for a protected environment:

1. Using the UI
   1. Set the Required approvals field to 1 or more.
2. Using the REST API 2. Set the required_approval_count field to 1 or more.

After this is configured, all jobs deploying to this environment automatically go into a blocked state and wait for approvals before running. Ensure that the number of required approvals is less than the number of users allowed to deploy.

Example:

curl --header 'Content-Type: application/json' --request POST \
     --data '{"name": "production", "deploy_access_levels": [{"group_id": 9899826}], "required_approval_count": 1}' \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     "https://gitlab.example.com/api/v4/projects/22034114/protected_environments"

NOTE: To protect, update, or unprotect an environment, you must have at least the Maintainer role.

Approve or reject a deployment

Introduced in GitLab 14.9

Using either the GitLab UI or the API, you can:

• Approve a deployment to allow it to proceed.
• Reject a deployment to prevent it.

Approve or reject a deployment using the UI

Prerequisites:

• Permission to deploy to the protected environment.

To approve or reject a deployment to a protected environment using the UI:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Deployments > Environments.
3. In the deployment's row, select Approval options ({thumb-up}).
4. Select Approve or Reject.

Approve or reject a deployment using the API

Prerequisites:

• Permission to deploy to the protected environment.

To approve or reject a deployment to a protected environment using the API, pass the required attributes. For more details, see Approve or reject a blocked deployment.

Example:

curl --data "status=approved&comment=Looks good to me" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/1/approval"

How to see blocked deployments

Using the UI

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Deployments > Environments.
3. Select the environment being deployed to.
4. Look for the blocked label.

Using the API

Use the Deployments API to see deployments.

• The status field indicates if a deployment is blocked.
• The pending_approval_count field indicates how many approvals are remaining to run a deployment.
• The approvals field contains the deployment's approvals.

Related features

For details about other GitLab features aimed at protecting deployments, see safe deployments.