Merge branch 'docs/environment-vars-clarify' into 'master'
Clarify what variables can be used under `environment:` See merge request gitlab-org/gitlab-ce!14277
This commit is contained in:
commit
6663db29ba
3 changed files with 69 additions and 57 deletions
|
@ -240,55 +240,18 @@ Remember that if your environment's name is `production` (all lowercase), then
|
||||||
it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).
|
it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md).
|
||||||
Double the benefit!
|
Double the benefit!
|
||||||
|
|
||||||
## Web terminals
|
|
||||||
|
|
||||||
>**Note:**
|
|
||||||
Web terminals were added in GitLab 8.15 and are only available to project
|
|
||||||
masters and owners.
|
|
||||||
|
|
||||||
If you deploy to your environments with the help of a deployment service (e.g.,
|
|
||||||
the [Kubernetes service][kubernetes-service], GitLab can open
|
|
||||||
a terminal session to your environment! This is a very 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 documentation.
|
|
||||||
|
|
||||||
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)
|
|
||||||
|
|
||||||
This works just like any other terminal - you'll be in the container created
|
|
||||||
by your deployment, so you can run shell commands and get responses in real
|
|
||||||
time, check the logs, try out configuration or code tweaks, etc. You can open
|
|
||||||
multiple terminals to the same environment - they each get their own shell
|
|
||||||
session - and even a multiplexer like `screen` or `tmux`!
|
|
||||||
|
|
||||||
>**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.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
While this is fine for deploying to some stable environments like staging or
|
|
||||||
production, what happens for branches? So far we haven't defined anything
|
|
||||||
regarding deployments for branches other than `master`. Dynamic environments
|
|
||||||
will help us achieve that.
|
|
||||||
|
|
||||||
## Dynamic environments
|
## Dynamic environments
|
||||||
|
|
||||||
As the name suggests, it is possible to create environments on the fly by just
|
As the name suggests, it is possible to create environments on the fly by just
|
||||||
declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments is
|
declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments is
|
||||||
the basis of [Review apps](review_apps/index.md).
|
the basis of [Review apps](review_apps/index.md).
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
The `name` and `url` parameters can use any of the defined CI variables,
|
||||||
|
including predefined, secure variables and `.gitlab-ci.yml`
|
||||||
|
[`variables`](yaml/README.md#variables).
|
||||||
|
You however cannot use variables defined under `script` or on the Runner's side.
|
||||||
|
|
||||||
GitLab Runner exposes various [environment variables][variables] when a job runs,
|
GitLab Runner exposes various [environment variables][variables] when a job runs,
|
||||||
and as such, you can use them as environment names. Let's add another job in
|
and as such, you can use them as environment names. Let's add another job in
|
||||||
our example which will deploy to all branches except `master`:
|
our example which will deploy to all branches except `master`:
|
||||||
|
@ -434,7 +397,8 @@ Let's briefly see where URL that's defined in the environments is exposed.
|
||||||
|
|
||||||
## Making use of the environment URL
|
## Making use of the environment URL
|
||||||
|
|
||||||
The environment URL is exposed in a few places within GitLab.
|
The [environment URL](yaml/README.md#environments-url) is exposed in a few
|
||||||
|
places within GitLab.
|
||||||
|
|
||||||
| In a merge request widget as a link | In the Environments view as a button | In the Deployments view as a button |
|
| In a merge request widget as a link | In the Environments view as a button | In the Deployments view as a button |
|
||||||
| -------------------- | ------------ | ----------- |
|
| -------------------- | ------------ | ----------- |
|
||||||
|
@ -622,6 +586,49 @@ version of the app, all without leaving GitLab.
|
||||||
|
|
||||||
![Monitoring dashboard](img/environments_monitoring.png)
|
![Monitoring dashboard](img/environments_monitoring.png)
|
||||||
|
|
||||||
|
## Web terminals
|
||||||
|
|
||||||
|
>**Note:**
|
||||||
|
Web terminals were added in GitLab 8.15 and are only available to project
|
||||||
|
masters and owners.
|
||||||
|
|
||||||
|
If you deploy to your environments with the help of a deployment service (e.g.,
|
||||||
|
the [Kubernetes service][kubernetes-service], GitLab can open
|
||||||
|
a terminal session to your environment! This is a very 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 documentation.
|
||||||
|
|
||||||
|
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)
|
||||||
|
|
||||||
|
This works just like any other terminal - you'll be in the container created
|
||||||
|
by your deployment, so you can run shell commands and get responses in real
|
||||||
|
time, check the logs, try out configuration or code tweaks, etc. You can open
|
||||||
|
multiple terminals to the same environment - they each get their own shell
|
||||||
|
session - and even a multiplexer like `screen` or `tmux`!
|
||||||
|
|
||||||
|
>**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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
While this is fine for deploying to some stable environments like staging or
|
||||||
|
production, what happens for branches? So far we haven't defined anything
|
||||||
|
regarding deployments for branches other than `master`. Dynamic environments
|
||||||
|
will help us achieve that.
|
||||||
|
|
||||||
## Checkout deployments locally
|
## Checkout deployments locally
|
||||||
|
|
||||||
Since 8.13, a reference in the git repository is saved for each deployment, so
|
Since 8.13, a reference in the git repository is saved for each deployment, so
|
||||||
|
|
|
@ -158,17 +158,17 @@ script:
|
||||||
settings. Follow the discussion in issue [#13784][ce-13784] for masking the
|
settings. Follow the discussion in issue [#13784][ce-13784] for masking the
|
||||||
secret variables.
|
secret variables.
|
||||||
|
|
||||||
GitLab CI allows you to define per-project or per-group **secret variables**
|
GitLab CI allows you to define per-project or per-group secret variables
|
||||||
that are set in the build environment. The secret variables are stored out of
|
that are set in the pipeline environment. The secret variables are stored out of
|
||||||
the repository (`.gitlab-ci.yml`) and are securely passed to GitLab Runner
|
the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner
|
||||||
making them available in the build environment. It's the recommended method to
|
making them available during a pipeline run. It's the recommended method to
|
||||||
use for storing things like passwords, secret keys and credentials.
|
use for storing things like passwords, SSH keys and credentials.
|
||||||
|
|
||||||
Project-level secret variables can be added by going to your project's
|
Project-level secret variables can be added by going to your project's
|
||||||
**Settings ➔ Pipelines**, then finding the section called **Secret variables**.
|
**Settings > CI/CD**, then finding the section called **Secret variables**.
|
||||||
|
|
||||||
Likewise, group-level secret variables can be added by going to your group's
|
Likewise, group-level secret variables can be added by going to your group's
|
||||||
**Settings ➔ Pipelines**, then finding the section called **Secret variables**.
|
**Settings > CI/CD**, then finding the section called **Secret variables**.
|
||||||
Any variables of [subgroups] will be inherited recursively.
|
Any variables of [subgroups] will be inherited recursively.
|
||||||
|
|
||||||
Once you set them, they will be available for all subsequent pipelines. You can also
|
Once you set them, they will be available for all subsequent pipelines. You can also
|
||||||
|
@ -185,8 +185,8 @@ protected, it would only be securely passed to pipelines running on the
|
||||||
protected variables.
|
protected variables.
|
||||||
|
|
||||||
Protected variables can be added by going to your project's
|
Protected variables can be added by going to your project's
|
||||||
**Settings ➔ Pipelines**, then finding the section called
|
**Settings > CI/CD**, then finding the section called
|
||||||
**Secret variables**, and check *Protected*.
|
**Secret variables**, and check "Protected".
|
||||||
|
|
||||||
Once you set them, they will be available for all subsequent pipelines.
|
Once you set them, they will be available for all subsequent pipelines.
|
||||||
|
|
||||||
|
|
|
@ -727,6 +727,9 @@ deployment to the `production` environment.
|
||||||
- Before GitLab 8.11, the name of an environment could be defined as a string like
|
- Before GitLab 8.11, the name of an environment could be defined as a string like
|
||||||
`environment: production`. The recommended way now is to define it under the
|
`environment: production`. The recommended way now is to define it under the
|
||||||
`name` keyword.
|
`name` keyword.
|
||||||
|
- The `name` parameter can use any of the defined CI variables,
|
||||||
|
including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
|
||||||
|
You however cannot use variables defined under `script`.
|
||||||
|
|
||||||
The `environment` name can contain:
|
The `environment` name can contain:
|
||||||
|
|
||||||
|
@ -762,6 +765,9 @@ deploy to production:
|
||||||
- Introduced in GitLab 8.11.
|
- Introduced in GitLab 8.11.
|
||||||
- Before GitLab 8.11, the URL could be added only in GitLab's UI. The
|
- Before GitLab 8.11, the URL could be added only in GitLab's UI. The
|
||||||
recommended way now is to define it in `.gitlab-ci.yml`.
|
recommended way now is to define it in `.gitlab-ci.yml`.
|
||||||
|
- The `url` parameter can use any of the defined CI variables,
|
||||||
|
including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
|
||||||
|
You however cannot use variables defined under `script`.
|
||||||
|
|
||||||
This is an optional value that when set, it exposes buttons in various places
|
This is an optional value that when set, it exposes buttons in various places
|
||||||
in GitLab which when clicked take you to the defined URL.
|
in GitLab which when clicked take you to the defined URL.
|
||||||
|
@ -841,10 +847,9 @@ The `stop_review_app` job is **required** to have the following keywords defined
|
||||||
**Notes:**
|
**Notes:**
|
||||||
- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
|
- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
|
||||||
- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
|
- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
|
||||||
|
- The `name` and `url` parameters can use any of the defined CI variables,
|
||||||
`environment` can also represent a configuration hash with `name` and `url`.
|
including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
|
||||||
These parameters can use any of the defined [CI variables](#variables)
|
You however cannot use variables defined under `script`.
|
||||||
(including predefined, secure variables and `.gitlab-ci.yml` variables).
|
|
||||||
|
|
||||||
For example:
|
For example:
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue