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 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 or unprotect an environment, you need at least the Maintainer role.
Additionally, to update environment attributes such as external_url, tier, or description,
you must also be in the Allowed to deploy list.
[!note] Protected environments are part of CI/CD settings. If CI/CD is turned off for the project, protected environments are unavailable in the UI and through the API. The API returns
403 Forbiddenfor all requests, including listing protected environments.
Prerequisites:
To protect an environment:
In the top bar, select Search or go to and find your project.
In the left sidebar, 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:
To update environment attributes such as external_url, tier, or description on a protected
environment, the user must also be in the Allowed to deploy list.
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 protected environments for groups, operators can restrict access to critical environments from developers. They extend the protected environments for projects to the group.
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)
Unlike protected environments for projects, protected environments for groups 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.
To maximize the effectiveness of protected environments for groups, group memberships must be correctly configured:
testing).Having this configuration in place:
To protect an environment for a group, make sure your environments have the correct
deployment_tier defined in .gitlab-ci.yml.
Configure protected environments for groups by using the REST API.
Protected environments can also be used to require manual approvals before deployments. See Deployment approvals for more information.
A job that uses the trigger keyword might not run, even with deployment-only access to protected environments.
This issue occurs when the trigger job doesn't have the environment keyword set. Without it, GitLab can't associate the job with the protected environment, so the job falls back to the regular CI/CD permission model, which doesn't grant the user's deployment-only role access to run it.
To resolve this issue, add the environment keyword directly to the trigger job.