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

stage	group	info	type
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	concepts, howto

Protected environments (PREMIUM)

Introduced in GitLab 11.3.

Environments can be used for different reasons:

• Some of them are just for testing.
• Others are for production.

Since deploy jobs can be raised by different users with different roles, it is important that specific environments are "protected" to prevent unauthorized people from affecting them.

By default, a protected environment does one thing: it ensures that only people with the right privileges can deploy to it, thus keeping it safe.

NOTE: A GitLab admin is always allowed to use environments, even if they are protected.

To protect, update, or unprotect an environment, you need to have at least the Maintainer role.

Protecting environments

To protect an environment:

1. On the top bar, select Menu > Projects and find your project.
2. On the left sidebar, select Settings > CI/CD.
3. Expand Protected environments.
4. From the Environment list, select the environment you want to protect.
5. In the Allowed to deploy list, select the role, users, or groups you want to give deploy access to. Keep in mind that:
   • There are two roles to choose from:
     • Maintainers: Allows access to all of the project's users with the Maintainer role.
     • Developers: Allows access to all of the project's users with the Maintainer and Developer role.
   • You can select groups that are already associated with the project only.
   • Users must have at least the Developer role to appear in the Allowed to deploy list.
6. Select Protect.

The protected environment now appears in the list of protected environments.

Use the API to protect an environment

Alternatively, you can use the API to protect an environment:

1. Use a project with a CI that creates an environment. For example:

   stages:
     - test
     - deploy
   
   test:
     stage: test
     script:
       - 'echo "Testing Application: ${CI_PROJECT_NAME}"'
   
   production:
     stage: deploy
     when: manual
     script:
       - 'echo "Deploying to ${CI_ENVIRONMENT_NAME}"'
     environment:
       name: ${CI_JOB_NAME}
   

2. Use the UI to create a new group. For example, this group is called protected-access-group and has the group ID 9899826. Note that the rest of the examples in these steps use this group.

   

3. Use the API to add a user to the group as a reporter:

   $ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
          --data "user_id=3222377&access_level=20" "https://gitlab.com/api/v4/groups/9899826/members"
   
   {"id":3222377,"name":"Sean Carroll","username":"sfcarroll","state":"active","avatar_url":"https://assets.gitlab-static.net/uploads/-/system/user/avatar/3222377/avatar.png","web_url":"https://gitlab.com/sfcarroll","access_level":20,"created_at":"2020-10-26T17:37:50.309Z","expires_at":null}
   

4. Use the API to add the group to the project as a reporter:

   $ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
          --request POST "https://gitlab.com/api/v4/projects/22034114/share?group_id=9899826&group_access=20"
   
   {"id":1233335,"project_id":22034114,"group_id":9899826,"group_access":20,"expires_at":null}
   

5. Use the API to add the group with protected environment access:

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

The group now has access and can be seen in the UI.

Environment access by group membership

A user may be granted access to protected environments as part of group membership. Users with Reporter permissions, can only be granted access to protected environments with this method.

Deployment branch access

Users with the Developer role can be granted access to a protected environment through any of these methods:

• As an individual contributor, through a role.
• Through a group membership.

If the user also has push or merge access to the branch deployed on production, they have the following privileges:

• Stop an environment.
• Delete a stopped environment.
• Create an environment terminal.

Deployment-only access to protected environments

Users granted access to a protected environment, but not push or merge access to the branch deployed to it, are only granted access to deploy the environment. An individual in a group with the Reporter permission, or in groups added to the project with Reporter permissions, appears in the dropdown menu for deployment-only access.

To add deployment-only access:

1. Add a group with the Reporter role.
2. Add users to the group.
3. Invite the group to be a project member.
4. Follow the steps in Protecting Environments.

Note that deployment-only access is the only possible access level for groups with Reporter permissions.

Modifying and unprotecting environments

Maintainers can:

• Update existing protected environments at any time by changing the access in the Allowed to Deploy dropdown menu.
• Unprotect a protected environment by clicking the Unprotect button for that environment.

After an environment is unprotected, all access entries are deleted and must be re-entered if the environment is re-protected.

For more information, see Deployment safety.

Group-level protected environments

• Introduced in GitLab 14.0. Deployed behind the group_level_protected_environments flag, disabled by default.
• Feature flag group_level_protected_environments removed in GitLab 14.3.
• Generally Available on GitLab and on GitLab.com in 14.3.

Typically, large enterprise organizations have an explicit permission boundary between developers and operators. Developers build and test their code, and operators deploy and monitor the application. With group-level protected environments, the permission of each group is carefully configured in order to prevent unauthorized access and maintain proper separation of duty. Group-level protected environments extend the project-level protected environments to the group-level.

The permissions of deployments can be illustrated in the following table:

Environment	Developer	Operator	Category
Development	Allowed	Allowed	Lower environment
Testing	Allowed	Allowed	Lower environment
Staging	Disallowed	Allowed	Higher environment
Production	Disallowed	Allowed	Higher environment

(Reference: Deployment environments on Wikipedia)

Group-level protected environments names

Contrary to project-level protected environments, group-level protected environments use the deployment tier as their name.

A group may consist of many project environments that have unique names. For example, Project-A has a gprd environment and Project-B has a Production environment, so protecting a specific environment name doesn't scale well. By using deployment tiers, both are recognized as production deployment tier and are protected at the same time.

Configure group-level memberships

In an enterprise organization, with thousands of projects under a single group, ensuring that all of the project-level protected environments are properly configured is not a scalable solution. For example, a developer might gain privileged access to a higher environment when they are added as a maintainer to a new project. Group-level protected environments can be a solution in this situation.

To maximize the effectiveness of group-level protected environments, group-level memberships must be correctly configured:

• Operators should be assigned the maintainer role (or above) to the top-level group. They can maintain CI/CD configurations for the higher environments (such as production) in the group-level settings page, which includes group-level protected environments, group-level runners, group-level clusters, etc. Those configurations are inherited to the child projects as read-only entries. This ensures that only operators can configure the organization-wide deployment ruleset.
• Developers should be assigned the developer role (or below) at the top-level group, or explicitly assigned to a child project as maintainers. They do NOT have access to the CI/CD configurations in the top-level group, so operators can ensure that the critical configuration won't be accidentally changed by the developers.
• For sub-groups and child projects:
  • Regarding sub-groups, if a higher group has configured the group-level protected environment, the lower groups cannot override it.
  • Project-level protected environments can be combined with the group-level setting. If both group-level and project-level environment configurations exist, to run a deployment job, the user must be allowed in both rulesets.
  • In a project or a subgroup of the top-level group, developers can be safely assigned the Maintainer role to tune their lower environments (such as testing).

Having this configuration in place:

• If a user is about to run a deployment job in a project and allowed to deploy to the environment, the deployment job proceeds.
• If a user is about to run a deployment job in a project but disallowed to deploy to the environment, the deployment job fails with an error message.

Protect a group-level environment

To protect a group-level environment:

1. Make sure your environments have the correct deployment_tier defined in .gitlab-ci.yml.
2. Configure the group-level protected environments via the REST API.

NOTE: Configuration via the UI is scheduled for a later release.