doc/ci/environments/protected_environments.md
{{< details >}}
{{< /details >}}
Environments can be used for both testing and production reasons.
Because deploy jobs can be raised by different users with different roles, it's important to be able to protect specific environments from the effects of unauthorized users.
By default, a protected environment ensures that only people with the appropriate privileges can deploy to it, keeping the environment safe.
[!note] GitLab administrators can use all environments, including protected environments.
To protect, update, or unprotect an environment, you need to have at least the Maintainer role.
Prerequisites:
To protect an environment:
In the top bar, select Search or go to and find your project.
Select Settings > CI/CD.
Expand Protected environments.
Select Protect an environment.
From the Environment list, select the environment you want to protect.
In the Allowed to deploy list, select the role, users, or groups you want to give deploy access to. Keep in mind that:
In the Approvers list, select the role, users, or groups you want to give deploy access to. Keep in mind that:
In the Approval rules section:
Select Protect.
The protected environment now appears in the list of protected environments.
Alternatively, you can use the API to protect an environment:
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}
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.
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://gitlab.com/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}
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}
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.
A user may be granted access to protected environments as part of group membership. Users with the Reporter role can only be granted access to protected environments with this method.
Users with the Developer role can be granted access to a protected environment through any of these methods:
If the user also has push or merge access to the branch deployed on production, they have the following privileges:
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. Invited groups added to the project with Reporter role, appear in the dropdown list for deployment-only access.
To add deployment-only access:
Maintainers can:
After an environment is unprotected, all access entries are deleted and must be re-entered if the environment is re-protected.
After an approval rule is deleted, previously approved deployments do not show who approved the deployment. Information on who approved a deployment is still available in the project audit events. If a new rule is added, previous deployments show the new rules without the option to approve the deployment. Issue 506687 proposes to show the full approval history of deployments, even if an approval rule is deleted.
For more information, see Deployment safety.
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, operators can restrict access to critical environments from developers. 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)
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.
{{< history >}}
group_level_protected_environment_settings_permission. Enabled by default.{{< /history >}}
To maximize the effectiveness of group-level protected environments, group-level memberships must be correctly configured:
testing).Having this configuration in place:
To protect a group-level environment, make sure your environments have the correct
deployment_tier defined in .gitlab-ci.yml.
{{< history >}}
{{< /history >}}
Configure the group-level protected environments by using the REST API.
Protected environments can also be used to require manual approvals before deployments. See Deployment approvals for more information.
A user who has deployment-only access to protected environments might not be able to run a job if it's with a trigger keyword. This is because the job is missing the environment keyword definition to associate the job with the protected environment, therefore the job is recognized as a standard job that uses regular CI/CD permission model.
See this issue for more information about supporting environment keyword with trigger keyword.