1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
---
stage: Release
group: Release
info: 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
type: concepts, howto
---
# Protected Environments **(PREMIUM)**
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3.
[Environments](../environments/index.md) 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
[Maintainer permissions](../../user/permissions.md).
## Protecting environments
To protect an environment:
1. Navigate to your project's **Settings > CI/CD**.
1. Expand the **Protected Environments** section.
1. From the **Environment** dropdown menu, select the environment you want to protect.
1. In the **Allowed to Deploy** dropdown menu, 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 maintainers in the project.
- **Developers**: Allows access to all maintainers and all developers in the project.
- You can only select groups that are already associated with the project.
- Only users that have at least the Developer permission level appear in
the **Allowed to Deploy** dropdown menu.
1. Click the **Protect** button.
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:
```yaml
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}
```
1. Use the UI to [create a new group](../../user/group/index.md#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.
1. Use the API to add a user to the group as a reporter:
```shell
$ 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}
```
1. Use the API to add the group to the project as a reporter:
```shell
$ 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}
```
1. Use the API to add the group with protected environment access:
```shell
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](../../user/group/index.md). Users with
[Reporter permissions](../../user/permissions.md), can only be granted access to
protected environments with this method.
## Deployment branch access
Users with [Developer permissions](../../user/permissions.md) 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:
- [Stopping an environment](index.md#stopping-an-environment).
- [Delete a stopped environment](index.md#delete-a-stopped-environment).
- [Create an environment terminal](index.md#web-terminals).
## 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.
Note that deployment-only access is the only possible access level for users with
[Reporter permissions](../../user/permissions.md).
## 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](deployment_safety.md).
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
|
