kotovalexarian-likes-gitlab/gitlab-org--gitlab-foss
1
0
Fork 0
Code Releases Activity

Merge branch 'docs/environment-vars-clarify' into 'master'

Browse source 
Clarify what variables can be used under `environment:`

See merge request gitlab-org/gitlab-ce!14277
This commit is contained in:
Rémy Coutable 2017-09-15 10:10:18 +00:00
commit 6663db29ba
3 changed files with 69 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

95
doc/ci/environments.md
View file

@ -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).
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
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
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,
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`:
@ -434,7 +397,8 @@ Let's briefly see where URL that's defined in the environments is exposed.
## 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 |
| -------------------- | ------------ | ----------- |
@ -622,6 +586,49 @@ version of the app, all without leaving GitLab.
![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
Since 8.13, a reference in the git repository is saved for each deployment, so

18
doc/ci/variables/README.md
View file

@ -158,17 +158,17 @@ script:
settings. Follow the discussion in issue [#13784][ce-13784] for masking the
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
the repository (`.gitlab-ci.yml`) and are securely passed to GitLab Runner
making them available in the build environment. It's the recommended method to
use for storing things like passwords, secret keys and credentials.
GitLab CI allows you to define per-project or per-group secret variables
that are set in the pipeline environment. The secret variables are stored out of
the repository (not in `.gitlab-ci.yml`) and are securely passed to GitLab Runner
making them available during a pipeline run. It's the recommended method to
use for storing things like passwords, SSH keys and credentials.
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
**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.
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 can be added by going to your project's
**Settings ➔ Pipelines**, then finding the section called
**Secret variables**, and check *Protected*.
**Settings > CI/CD**, then finding the section called
**Secret variables**, and check "Protected".
Once you set them, they will be available for all subsequent pipelines.

13
doc/ci/yaml/README.md
View file

@ -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
`environment: production`. The recommended way now is to define it under the
`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:
@ -762,6 +765,9 @@ deploy to production:
- Introduced in GitLab 8.11.
- 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`.
- 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
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:**
- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
`environment` can also represent a configuration hash with `name` and `url`.
These parameters can use any of the defined [CI variables](#variables)
(including predefined, secure variables and `.gitlab-ci.yml` variables).
- The `name` and `url` parameters 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`.
For example: