environments.md 27,2 КБ
Newer Older
Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
1
2
3
4
---
type: reference
---

Evan Read's avatar
Evan Read включено в состав коммита
5
# Environments and deployments
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
6

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
7
> Introduced in GitLab 8.9.
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
8

Evan Read's avatar
Evan Read включено в состав коммита
9
10
Environments allow control of the continuous deployment of your software,
all within GitLab.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
11

Evan Read's avatar
Evan Read включено в состав коммита
12
13
14
15
16
17
18
19
20
21
22
## Introduction

There are many stages required in the software development process before the software is ready
for public consumption.

For example:

1. Develop your code.
1. Test your code.
1. Deploy your code into a testing or staging environment before you release it to the public.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
23
This helps find bugs in your software, and also in the deployment process as well.
Evan Read's avatar
Evan Read включено в состав коммита
24
25

GitLab CI/CD is capable of not only testing or building your projects, but also
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
26
deploying them in your infrastructure, with the added benefit of giving you a
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
27
way to track your deployments. In other words, you will always know what is
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
28
currently being deployed or has been deployed on your servers.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
29

Evan Read's avatar
Evan Read включено в состав коммита
30
It's important to know that:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
31

Evan Read's avatar
Evan Read включено в состав коммита
32
33
34
- Environments are like tags for your CI jobs, describing where code gets deployed.
- Deployments are created when [jobs](yaml/README.md#introduction) deploy versions of code to environments,
  so every environment can have one or more deployments.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
35

Evan Read's avatar
Evan Read включено в состав коммита
36
37
GitLab:

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
38
- Provides a full history of your deployments for each environment.
Evan Read's avatar
Evan Read включено в состав коммита
39
40
41
42
- Keeps track of your deployments, so you always know what is currently being deployed on your
  servers.

If you have a deployment service such as [Kubernetes](../user/project/clusters/index.md)
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
43
associated with your project, you can use it to assist with your deployments, and
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
44
can even access a [web terminal](#web-terminals) for your environment from within GitLab!
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
45

Evan Read's avatar
Evan Read включено в состав коммита
46
47
48
49
50
51
52
## Configuring environments

Configuring environments involves:

1. Understanding how [pipelines](pipelines.md) work.
1. Defining environments in your project's [`.gitlab-ci.yml`](yaml/README.md) file.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
53
54
The rest of this section illustrates how to configure environments and deployments using
an example scenario. It assumes you have already:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
55

Evan Read's avatar
Evan Read включено в состав коммита
56
57
- Created a [project](../gitlab-basics/create-project.md) in GitLab.
- Set up [a Runner](runners/README.md).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
58

Evan Read's avatar
Evan Read включено в состав коммита
59
In the scenario:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
60

Evan Read's avatar
Evan Read включено в состав коммита
61
62
63
64
65
66
- We are developing an application.
- We want to run tests and build our app on all branches.
- Our default branch is `master`.
- We deploy the app only when a pipeline on `master` branch is run.

### Defining environments
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
67

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
68
Let's consider the following `.gitlab-ci.yml` example:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
69

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
70
71
72
73
74
```yaml
stages:
  - test
  - build
  - deploy
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
75

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
76
77
78
test:
  stage: test
  script: echo "Running tests"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
79

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
80
81
82
build:
  stage: build
  script: echo "Building the app"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
83

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
84
85
86
deploy_staging:
  stage: deploy
  script:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
87
    - echo "Deploy to staging server"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
88
  environment:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
89
90
    name: staging
    url: https://staging.example.com
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
91
92
93
  only:
  - master
```
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
94

Evan Read's avatar
Evan Read включено в состав коммита
95
We have defined three [stages](yaml/README.md#stages):
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
96

Evan Read's avatar
Evan Read включено в состав коммита
97
98
99
- `test`
- `build`
- `deploy`
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
100

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
101
102
The jobs assigned to these stages will run in this order. If any job fails, then
the pipeline fails and jobs that are assigned to the next stage won't run.
Evan Read's avatar
Evan Read включено в состав коммита
103
104
105
106
107
108
109

In our case:

- The `test` job will run first.
- Then the `build` job.
- Lastly the `deploy_staging` job.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
110
With this configuration, we:
Evan Read's avatar
Evan Read включено в состав коммита
111

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
112
113
- Check that the tests pass.
- Ensure that our app is able to be built successfully.
Evan Read's avatar
Evan Read включено в состав коммита
114
- Lastly we deploy to the staging server.
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
115

Evan Read's avatar
Evan Read включено в состав коммита
116
NOTE: **Note:**
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
117
The `environment` keyword is just a hint for GitLab that this job actually
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
118
deploys to the `name` environment. It can also have a `url` that is
Evan Read's avatar
Evan Read включено в состав коммита
119
120
exposed in various places within GitLab. Each time a job that
has an environment specified succeeds, a deployment is recorded, storing
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
121
122
the Git SHA and environment name.

Evan Read's avatar
Evan Read включено в состав коммита
123
124
125
126
127
128
129
130
131
132
In summary, with the above `.gitlab-ci.yml` we have achieved the following:

- All branches will run the `test` and `build` jobs.
- The `deploy_staging` job will run [only](yaml/README.md#onlyexcept-basic) on the `master`
  branch, which means all merge requests that are created from branches don't
  get deployed to the staging server.
- When a merge request is merged, all jobs will run and the `deploy_staging`
  job will deploy our code to a staging server while the deployment
  will be recorded in an environment named `staging`.

Brett Walker's avatar
Brett Walker включено в состав коммита
133
134
135
136
137
> Starting with GitLab 8.15, the environment name is exposed to the Runner in
> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is
> the name given in `.gitlab-ci.yml` (with any variables expanded), while the
> second is a "cleaned-up" version of the name, suitable for use in URLs, DNS,
> etc.
Evan Read's avatar
Evan Read включено в состав коммита
138
>
Brett Walker's avatar
Brett Walker включено в состав коммита
139
> Starting with GitLab 9.3, the environment URL is exposed to the Runner via
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
140
141
> `$CI_ENVIRONMENT_URL`. The URL is expanded from `.gitlab-ci.yml`, or if
> the URL was not defined there, the external URL from the environment is used.
Lin Jen-Shin's avatar
Lin Jen-Shin включено в состав коммита
142

Evan Read's avatar
Evan Read включено в состав коммита
143
### Configuring manual deployments
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
144

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
145
146
Adding `when: manual` to an automatically executed job's configuration converts it to
a job requiring manual action.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
147

Evan Read's avatar
Evan Read включено в состав коммита
148
149
150
To expand on the [previous example](#defining-environments), the following includes
another job that deploys our app to a production server and is
tracked by a `production` environment.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
151

Evan Read's avatar
Evan Read включено в состав коммита
152
The `.gitlab-ci.yml` file for this is as follows:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
153

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
```yaml
stages:
  - test
  - build
  - deploy

test:
  stage: test
  script: echo "Running tests"

build:
  stage: build
  script: echo "Building the app"

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com
  only:
  - master

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
  - master
```

Evan Read's avatar
Evan Read включено в состав коммита
190
191
The `when: manual` action:

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
192
- Exposes a "play" button in GitLab's UI for that job.
Evan Read's avatar
Evan Read включено в состав коммита
193
- Means the `deploy_prod` job will only be triggered when the "play" button is clicked.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
194

Evan Read's avatar
Evan Read включено в состав коммита
195
You can find the "play" button in the pipelines, environments, deployments, and jobs views.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
196

Evan Read's avatar
Evan Read включено в состав коммита
197
198
199
200
201
202
203
204
| View            | Screenshot                                                                     |
|:----------------|:-------------------------------------------------------------------------------|
| Pipelines       | ![Pipelines manual action](img/environments_manual_action_pipelines.png)       |
| Single pipeline | ![Pipelines manual action](img/environments_manual_action_single_pipeline.png) |
| Environments    | ![Environments manual action](img/environments_manual_action_environments.png) |
| Deployments     | ![Deployments manual action](img/environments_manual_action_deployments.png)   |
| Jobs            | ![Builds manual action](img/environments_manual_action_jobs.png)               |

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
205
206
Clicking on the play button in any view will trigger the `deploy_prod` job, and the
deployment will be recorded as a new environment named `production`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
207

Evan Read's avatar
Evan Read включено в состав коммита
208
209
NOTE: **Note:**
If your environment's name is `production` (all lowercase),
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
210
211
it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).

Evan Read's avatar
Evan Read включено в состав коммита
212
### Configuring dynamic environments
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
213

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
214
Regular environments are good when deploying to "stable" environments like staging or production.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
215

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
216
217
However, for environments for branches other than `master`, dynamic environments
can be used. Dynamic environments make it possible to create environments on the fly by
Evan Read's avatar
Evan Read включено в состав коммита
218
219
declaring their names dynamically in `.gitlab-ci.yml`.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
220
Dynamic environments are a fundamental part of [Review apps](review_apps/index.md).
Evan Read's avatar
Evan Read включено в состав коммита
221
222
223
224
225
226
227

#### Allowed variables

The `name` and `url` parameters for dynamic environments can use most available CI/CD variables,
including:

- [Predefined environment variables](variables/README.md#predefined-environment-variables)
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
228
- [Project and group variables](variables/README.md#gitlab-cicd-environment-variables)
Evan Read's avatar
Evan Read включено в состав коммита
229
230
231
232
233
234
235
236
237
238
239
240
- [`.gitlab-ci.yml` variables](yaml/README.md#variables)

However, you cannot use variables defined:

- Under `script`.
- On the Runner's side.

There are also other variables that are unsupported in the context of `environment:name`.
For more information, see [Where variables can be used](variables/where_variables_can_be_used.md).

#### Example configuration

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
241
GitLab Runner exposes various [environment variables](variables/README.md) when a job runs, so
Evan Read's avatar
Evan Read включено в состав коммита
242
243
you can use them as environment names.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
244
In the following example, the job will deploy to all branches except `master`:
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
245

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
246
247
248
249
250
251
```yaml
deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
252
    name: review/$CI_COMMIT_REF_NAME
Vincent Tunru's avatar
Vincent Tunru включено в состав коммита
253
    url: https://$CI_ENVIRONMENT_SLUG.example.com
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
254
255
256
257
  only:
    - branches
  except:
    - master
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
258
```
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
259

Evan Read's avatar
Evan Read включено в состав коммита
260
261
262
263
264
In this example:

- The job's name is `deploy_review` and it runs on the `deploy` stage.
- We set the `environment` with the `environment:name` as `review/$CI_COMMIT_REF_NAME`.
  Since the [environment name](yaml/README.md#environmentname) can contain slashes (`/`), we can
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
265
266
267
  use this pattern to distinguish between dynamic and regular environments.
- We tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches,
  [`except`](yaml/README.md#onlyexcept-basic) `master`.
Evan Read's avatar
Evan Read включено в состав коммита
268
269
270
271

For the value of:

- `environment:name`, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`,
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
272
273
274
  which receives the value of the branch name.
- `environment:url`, we want a specific and distinct URL for each branch. `$CI_COMMIT_REF_NAME`
  may contain a `/` or other characters that would be invalid in a domain name or URL,
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
275
  so we use `$CI_ENVIRONMENT_SLUG` to guarantee that we get a valid URL.
Evan Read's avatar
Evan Read включено в состав коммита
276
277
278
279
280

  For example, given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something
  like `https://100-do-the-4f99a2.example.com`. Again, the way you set up
  the web server to serve these requests is based on your setup.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
281
282
283
284
285
286
  We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If
  you're using a workflow like [GitLab Flow](../workflow/gitlab_flow.md), collisions
  are unlikely and you may prefer environment names to be more closely based on the
  branch name. In that case, you could use `$CI_COMMIT_REF_SLUG` in `environment:url` in
  the example above: `https://$CI_COMMIT_REF_SLUG.example.com`, which would give a URL
  of `https://100-do-the-thing.example.com`.
Evan Read's avatar
Evan Read включено в состав коммита
287
288

NOTE: **Note:**
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
289
290
291
You are not required to use the same prefix or only slashes (`/`) in the dynamic environments'
names. However, using this format will enable the [grouping similar environments](#grouping-similar-environments)
feature.
Evan Read's avatar
Evan Read включено в состав коммита
292
293
294
295
296
297
298
299
300

### Complete example

The configuration in this section provides a full development workflow where your app is:

- Tested.
- Built.
- Deployed as a Review App.
- Deployed to a staging server once the merge request is merged.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
301
- Finally, able to be manually deployed to the production server.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
302

Evan Read's avatar
Evan Read включено в состав коммита
303
304
305
306
307
The following combines the previous configuration examples, including:

- Defining [simple environments](#defining-environments) for testing, building, and deployment to staging.
- Adding [manual actions](#configuring-manual-deployments) for deployment to production.
- Creating [dynamic environments](#configuring-dynamic-environments) for deployments for reviewing.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323

```yaml
stages:
  - test
  - build
  - deploy

test:
  stage: test
  script: echo "Running tests"

build:
  stage: build
  script: echo "Building the app"

deploy_review:
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
324
  stage: deploy
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
325
  script:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
326
    - echo "Deploy a review app"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
327
  environment:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
328
    name: review/$CI_COMMIT_REF_NAME
Nick Thomas's avatar
Nick Thomas включено в состав коммита
329
    url: https://$CI_ENVIRONMENT_SLUG.example.com
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
  only:
    - branches
  except:
    - master

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com
  only:
  - master

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
  - master
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
355
356
```

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
357
A more realistic example would also include copying files to a location where a
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
358
webserver (for example, NGINX) could then access and serve them.
Evan Read's avatar
Evan Read включено в состав коммита
359
360

The example below will copy the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
361
362
363
364
365

```yaml
review_app:
  stage: deploy
  script:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
366
    - rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
367
  environment:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
368
369
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_COMMIT_REF_SLUG.example.com
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
370
371
```

Evan Read's avatar
Evan Read включено в состав коммита
372
373
374
This example requires that NGINX and GitLab Runner are set up on the server this job will run on.

NOTE: **Note:**
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
375
376
See the [limitations](#limitations) section for some edge cases regarding the naming of
your branches and Review Apps.
Evan Read's avatar
Evan Read включено в состав коммита
377

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
378
The complete example provides the following workflow to developers:
Evan Read's avatar
Evan Read включено в состав коммита
379
380

- Create a branch locally.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
381
- Make changes and commit them.
Evan Read's avatar
Evan Read включено в состав коммита
382
383
384
- Push the branch to GitLab.
- Create a merge request.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
385
Behind the scenes, GitLab Runner will:
Evan Read's avatar
Evan Read включено в состав коммита
386
387
388
389
390

- Pick up the changes and start running the jobs.
- Run the jobs sequentially as defined in `stages`:
  - First, run the tests.
  - If the tests succeed, build the app.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
391
  - If the build succeeds, the app is deployed to an environment with a name specific to the
Evan Read's avatar
Evan Read включено в состав коммита
392
393
394
395
396
    branch.

So now, every branch:

- Gets its own environment.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
397
- Is deployed to its own unique location, with the added benefit of:
Evan Read's avatar
Evan Read включено в состав коммита
398
399
400
  - Having a [history of deployments](#viewing-deployment-history).
  - Being able to [rollback changes](#retrying-and-rolling-back) if needed.

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
401
For more information, see [Using the environment URL](#using-the-environment-url).
Evan Read's avatar
Evan Read включено в состав коммита
402
403
404
405
406
407
408
409
410

### Protected environments

Environments can be "protected", restricting access to them.

For more information, see [Protected environments](environments/protected_environments.md).

## Working with environments

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
411
412
Once environments are configured, GitLab provides many features for working with them,
as documented below.
Evan Read's avatar
Evan Read включено в состав коммита
413
414
415

### Viewing environments and deployments

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
416
A list of environments and deployment statuses is available on each project's **Operations > Environments** page.
Evan Read's avatar
Evan Read включено в состав коммита
417
418
419
420
421
422
423
424
425
426

For example:

![Environment view](img/environments_available.png)

This example shows:

- The environment's name with a link to its deployments.
- The last deployment ID number and who performed it.
- The job ID of the last deployment with its respective job name.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
427
- The commit information of the last deployment, such as who committed it, to what
Evan Read's avatar
Evan Read включено в состав коммита
428
429
  branch, and the Git SHA of the commit.
- The exact time the last deployment was performed.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
430
431
- A button that takes you to the URL that you defined under the `environment` keyword
  in `.gitlab-ci.yml`.
Evan Read's avatar
Evan Read включено в состав коммита
432
433
434
435
436
437
438
439
440
441
442
- A button that re-deploys the latest deployment, meaning it runs the job
  defined by the environment name for that specific commit.

The information shown in the **Environments** page is limited to the latest
deployments, but an environment can have multiple deployments.

> **Notes:**
>
> - While you can create environments manually in the web interface, we recommend
>   that you define your environments in `.gitlab-ci.yml` first. They will
>   be automatically created for you after the first deploy.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
443
444
> - The environments page can only be viewed by users with [Reporter permission](../user/permissions.md#project-members-permissions)
>   and above. For more information on permissions, see the [permissions documentation](../user/permissions.md).
Evan Read's avatar
Evan Read включено в состав коммита
445
446
447
448
449
450
451
452
> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured
>   will show up in the **Environment** and **Last deployment** lists.

### Viewing deployment history

GitLab keeps track of your deployments, so you:

- Always know what is currently being deployed on your servers.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
453
- Can have the full history of your deployments for every environment.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
454

Evan Read's avatar
Evan Read включено в состав коммита
455
456
Clicking on an environment shows the history of its deployments. Here's an example **Environments** page
with multiple deployments:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
457

Evan Read's avatar
Evan Read включено в состав коммита
458
459
460
461
![Deployments](img/deployments_view.png)

This view is similar to the **Environments** page, but all deployments are shown. Also in this view
is a **Rollback** button. For more information, see [Retrying and rolling back](#retrying-and-rolling-back).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
462

Evan Read's avatar
Evan Read включено в состав коммита
463
### Retrying and rolling back
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
464

Evan Read's avatar
Evan Read включено в состав коммита
465
If there is a problem with a deployment, you can retry it or roll it back.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
466

Evan Read's avatar
Evan Read включено в состав коммита
467
To retry or rollback a deployment:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
468

Evan Read's avatar
Evan Read включено в состав коммита
469
470
1. Navigate to **Operations > Environments**.
1. Click on the environment.
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
471
472
473
1. In the deployment history list for the environment, click the:
   - **Retry** button next to the last deployment, to retry that deployment.
   - **Rollback** button next to a previously successful deployment, to roll back to that deployment.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
474

Evan Read's avatar
Evan Read включено в состав коммита
475
476
NOTE: **Note:**
The defined deployment process in the job's `script` determines whether the rollback succeeds or not.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
477

Evan Read's avatar
Evan Read включено в состав коммита
478
### Using the environment URL
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
479

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
480
The [environment URL](yaml/README.md#environmenturl) is exposed in a few
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
481
places within GitLab:
Evan Read's avatar
Evan Read включено в состав коммита
482
483
484
485
486
487
488

- In a merge request widget as a link:
  ![Environment URL in merge request](img/environments_mr_review_app.png)
- In the Environments view as a button:
  ![Environment URL in environments](img/environments_available.png)
- In the Deployments view as a button:
  ![Environment URL in deployments](img/deployments_view.png)
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
489

Evan Read's avatar
Evan Read включено в состав коммита
490
491
492
493
494
495
You can see this information in a merge request itself if:

- The merge request is eventually merged to the default branch (usually `master`).
- That branch also deploys to an environment (for example, `staging` or `production`).

For example:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
496
497
498

![Environment URLs in merge request](img/environments_link_url_mr.png)

Evan Read's avatar
Evan Read включено в состав коммита
499
#### Going from source files to public pages
Douwe Maan's avatar
Douwe Maan включено в состав коммита
500

Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
501
With GitLab's [Route Maps](review_apps/index.md#route-maps) you can go directly
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
502
from source files to public pages in the environment set for Review Apps.
Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
503

Evan Read's avatar
Evan Read включено в состав коммита
504
### Stopping an environment
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
505

Evan Read's avatar
Evan Read включено в состав коммита
506
Stopping an environment:
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
507

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
508
509
- Moves it from the list of **Available** environments to the list of **Stopped**
  environments on the [**Environments** page](#viewing-environments-and-deployments).
Evan Read's avatar
Evan Read включено в состав коммита
510
- Executes an [`on_stop` action](yaml/README.md#environmenton_stop), if defined.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
511

Evan Read's avatar
Evan Read включено в состав коммита
512
513
This is often used when multiple developers are working on a project at the same time,
each of them pushing to their own branches, causing many dynamic environments to be created.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
514

Evan Read's avatar
Evan Read включено в состав коммита
515
NOTE: **Note:**
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
516
Starting with GitLab 8.14, dynamic environments are stopped automatically
Evan Read's avatar
Evan Read включено в состав коммита
517
518
519
520
521
when their associated branch is deleted.

#### Automatically stopping an environment

Environments can be stopped automatically using special configuration.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
522

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
523
Consider the following example where the `deploy_review` job calls `stop_review`
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
524
525
526
527
to clean up and stop the environment:

```yaml
deploy_review:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
528
529
  stage: deploy
  script:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
530
    - echo "Deploy a review app"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
531
  environment:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
532
    name: review/$CI_COMMIT_REF_NAME
Nick Thomas's avatar
Nick Thomas включено в состав коммита
533
    url: https://$CI_ENVIRONMENT_SLUG.example.com
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
534
    on_stop: stop_review
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
535
536
537
538
  only:
    - branches
  except:
    - master
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
539
540

stop_review:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
541
  stage: deploy
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
542
543
  variables:
    GIT_STRATEGY: none
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
544
545
  script:
    - echo "Remove review app"
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
546
547
  when: manual
  environment:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
548
    name: review/$CI_COMMIT_REF_NAME
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
549
550
    action: stop
```
Mark Pundsack's avatar
Mark Pundsack включено в состав коммита
551

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
552
553
554
Setting the [`GIT_STRATEGY`](yaml/README.md#git-strategy) to `none` is necessary in the
`stop_review` job so that the [GitLab Runner](https://docs.gitlab.com/runner/) won't
try to check out the code after the branch is deleted.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
555

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
556
When you have an environment that has a stop action defined (typically when
Evan Read's avatar
Evan Read включено в состав коммита
557
the environment describes a Review App), GitLab will automatically trigger a
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
558
stop action when the associated branch is deleted. The `stop_review` job must
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
559
be in the same `stage` as the `deploy_review` job in order for the environment
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
560
to automatically stop.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
561

Evan Read's avatar
Evan Read включено в состав коммита
562
You can read more in the [`.gitlab-ci.yml` reference](yaml/README.md#environmenton_stop).
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
563

Evan Read's avatar
Evan Read включено в состав коммита
564
### Grouping similar environments
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
565

Evan Read's avatar
Evan Read включено в состав коммита
566
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015) in GitLab 8.14.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
567

Evan Read's avatar
Evan Read включено в состав коммита
568
569
570
As documented in [Configuring dynamic environments](#configuring-dynamic-environments), you can
prepend environment name with a word, followed by a `/`, and finally the branch
name, which is automatically defined by the `CI_COMMIT_REF_NAME` variable.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
571

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
572
573
In short, environments that are named like `type/foo` are all presented under the same
group, named `type`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
574

Evan Read's avatar
Evan Read включено в состав коммита
575
576
In our [minimal example](#example-configuration), we named the environments `review/$CI_COMMIT_REF_NAME`
where `$CI_COMMIT_REF_NAME` is the branch name. Here is a snippet of the example:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
577
578
579
580
581
582
583

```yaml
deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
Z.J. van de Weg's avatar
Z.J. van de Weg включено в состав коммита
584
    name: review/$CI_COMMIT_REF_NAME
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
585
586
```

Evan Read's avatar
Evan Read включено в состав коммита
587
In this case, if you visit the **Environments** page and the branches
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
588
589
590
exist, you should see something like:

![Environment groups](img/environments_dynamic_groups.png)
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
591

Evan Read's avatar
Evan Read включено в состав коммита
592
### Monitoring environments
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
593

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
594
If you have enabled [Prometheus for monitoring system and response metrics](../user/project/integrations/prometheus.md),
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
595
596
597
598
599
600
you can monitor the behavior of your app running in each environment. For the monitoring
dashboard to appear, you need to Configure Prometheus to collect at least one
[supported metric](../user/project/integrations/prometheus_library/index.md).

NOTE: **Note:**
Since GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
601

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
602
603
Once configured, GitLab will attempt to retrieve [supported performance metrics](../user/project/integrations/prometheus_library/index.md)
for any environment that has had a successful deployment. If monitoring data was
Evan Read's avatar
Evan Read включено в состав коммита
604
successfully retrieved, a **Monitoring** button will appear for each environment.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
605

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
606
![Environment Detail with Metrics](img/deployments_view.png)
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
607

Evan Read's avatar
Evan Read включено в состав коммита
608
Clicking on the **Monitoring** button will display a new page showing up to the last
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
609
610
611
8 hours of performance data. It may take a minute or two for data to appear
after initial deployment.

Evan Read's avatar
Evan Read включено в состав коммита
612
All deployments to an environment are shown directly on the monitoring dashboard,
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
613
614
which allows easy correlation between any changes in performance and new
versions of the app, all without leaving GitLab.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
615
616
617

![Monitoring dashboard](img/environments_monitoring.png)

Reuben Pereira's avatar
Reuben Pereira включено в состав коммита
618
619
620
621
#### Linking to external dashboard

Add a [button to the Monitoring dashboard](../user/project/operations/linking_to_an_external_dashboard.md) linking directly to your existing external dashboards.

Tristan Read's avatar
Tristan Read включено в состав коммита
622
623
624
625
#### Embedding metrics in GitLab Flavored Markdown

Metric charts can be embedded within GitLab Flavored Markdown. See [Embedding Metrics within GitLab Flavored Markdown](../user/project/integrations/prometheus.md#embedding-metric-charts-within-gitlab-flavored-markdown) for more details.

Evan Read's avatar
Evan Read включено в состав коммита
626
627
628
### Web terminals

> Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
629

Evan Read's avatar
Evan Read включено в состав коммита
630
631
632
If you deploy to your environments with the help of a deployment service (for example,
the [Kubernetes integration](../user/project/clusters/index.md)), GitLab can open
a terminal session to your environment.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
633

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
634
635
This is a powerful feature that allows you to debug issues without leaving the comfort
of your web browser. To enable it, just follow the instructions given in the service integration
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
636
documentation.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
637
638
639
640
641
642
643
644
645
646
647
648
649
650

Once enabled, your environments will gain a "terminal" button:

![Terminal button on environment index](img/environments_terminal_button_on_index.png)

You can also access the terminal button from the page for a specific environment:

![Terminal button for an environment](img/environments_terminal_button_on_show.png)

Wherever you find it, clicking the button will take you to a separate page to
establish the terminal session:

![Terminal page](img/environments_terminal_page.png)

Evan Read's avatar
Evan Read включено в состав коммита
651
652
This works just like any other terminal. You'll be in the container created
by your deployment so you can:
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
653

Evan Read's avatar
Evan Read включено в состав коммита
654
655
656
- Run shell commands and get responses in real time.
- Check the logs.
- Try out configuration or code tweaks etc.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
657

Evan Read's avatar
Evan Read включено в состав коммита
658
659
You can open multiple terminals to the same environment, they each get their own shell
session and even a multiplexer like `screen` or `tmux`.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
660

Evan Read's avatar
Evan Read включено в состав коммита
661
662
663
664
NOTE: **Note:**
Container-based deployments often lack basic tools (like an editor), and may
be stopped or restarted at any time. If this happens, you will lose all your
changes. Treat this as a debugging tool, not a comprehensive online IDE.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
665

Evan Read's avatar
Evan Read включено в состав коммита
666
### Check out deployments locally
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
667

Evan Read's avatar
Evan Read включено в состав коммита
668
Since GitLab 8.13, a reference in the Git repository is saved for each deployment, so
Nick Thomas's avatar
Nick Thomas включено в состав коммита
669
knowing the state of your current environments is only a `git fetch` away.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
670

Evan Read's avatar
Evan Read включено в состав коммита
671
In your Git configuration, append the `[remote "<your-remote>"]` block with an extra
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
672
673
fetch line:

Evan Read's avatar
Evan Read включено в состав коммита
674
```text
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
675
676
677
fetch = +refs/environments/*:refs/remotes/origin/environments/*
```

Nicolas Borderes's avatar
Nicolas Borderes включено в состав коммита
678
### Scoping environments with specs
Evan Read's avatar
Evan Read включено в состав коммита
679

Nicolas Borderes's avatar
Nicolas Borderes включено в состав коммита
680
681
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/30779) to Core in Gitlab 12.2.
Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697

You can limit the environment scope of a variable by
defining which environments it can be available for.

Wildcards can be used, and the default environment scope is `*`, which means
any jobs will have this variable, not matter if an environment is defined or
not.

For example, if the environment scope is `production`, then only the jobs
having the environment `production` defined would have this specific variable.
Wildcards (`*`) can be used along with the environment name, therefore if the
environment scope is `review/*` then any jobs with environment names starting
with `review/` would have that particular variable.

Some GitLab features can behave differently for each environment.
For example, you can
Hordur Freyr Yngvason's avatar
Hordur Freyr Yngvason включено в состав коммита
698
[create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-environment-variables).
Evan Read's avatar
Evan Read включено в состав коммита
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721

In most cases, these features use the _environment specs_ mechanism, which offers
an efficient way to implement scoping within each environment group.

Let's say there are four environments:

- `production`
- `staging`
- `review/feature-1`
- `review/feature-2`

Each environment can be matched with the following environment spec:

| Environment Spec | `production` | `staging` | `review/feature-1` | `review/feature-2` |
|:-----------------|:-------------|:----------|:-------------------|:-------------------|
| *                | Matched      | Matched   | Matched            | Matched            |
| production       | Matched      |           |                    |                    |
| staging          |              | Matched   |                    |                    |
| review/*         |              |           | Matched            | Matched            |
| review/feature-1 |              |           | Matched            |                    |

As you can see, you can use specific matching for selecting a particular environment,
and also use wildcard matching (`*`) for selecting a particular environment group,
Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
722
such as [Review Apps](review_apps/index.md) (`review/*`).
Evan Read's avatar
Evan Read включено в состав коммита
723
724
725
726
727

NOTE: **Note:**
The most _specific_ spec takes precedence over the other wildcard matching.
In this case, `review/feature-1` spec takes precedence over `review/*` and `*` specs.

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
728
729
## Limitations

Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
730
731
In the `environment: name`, you are limited to only the [predefined environment variables](variables/predefined_variables.md).
Re-using variables defined inside `script` as part of the environment name will not work.
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
732

Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
733
734
735
736
737
738
## Further reading

Below are some links you may find interesting:

- [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment)
- [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/)
Achilleas Pipinellis's avatar
Achilleas Pipinellis включено в состав коммита
739
- [Review Apps - Use dynamic environments to deploy your code for every branch](review_apps/index.md)
Marcel Amirault's avatar
Marcel Amirault включено в состав коммита
740
- [Deploy Boards for your applications running on Kubernetes](../user/project/deploy_boards.md) **(PREMIUM)**
Marcia Ramos's avatar
Marcia Ramos включено в состав коммита
741
742
743
744
745
746
747
748
749
750
751
752

<!-- ## 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. -->