2019-05-18 00:54:41 +05:30
# Environments and deployments
2016-06-22 15:30:34 +05:30
2017-08-17 22:00:37 +05:30
> Introduced in GitLab 8.9.
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
Environments allow control of the continuous deployment of your software,
all within GitLab.
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
## 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.
This helps prevent bugs not only in your software, but in the deployment process as well.
GitLab CI/CD is capable of not only testing or building your projects, but also
2017-08-17 22:00:37 +05:30
deploying them in your infrastructure, with the added benefit of giving you a
way to track your deployments. In other words, you can always know what is
currently being deployed or has been deployed on your servers.
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
It's important to know that:
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
- 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.
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
GitLab:
- Provides a full history of your deployments per every environment.
- 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 )
2017-08-17 22:00:37 +05:30
enabled for your project, you can use it to assist with your deployments, and
2018-03-17 18:26:18 +05:30
can even access a [web terminal ](#web-terminals ) for your environment from within GitLab!
2016-11-03 12:29:30 +05:30
2019-05-18 00:54:41 +05:30
## 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.
The rest of this section illustrates how to configure environments and deployments using an example.
It assumes you have already:
2016-11-03 12:29:30 +05:30
2019-05-18 00:54:41 +05:30
- Created a [project ](../gitlab-basics/create-project.md ) in GitLab.
- Set up [a Runner ](runners/README.md ).
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
In the scenario:
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
- 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
2017-08-17 22:00:37 +05:30
Let's consider the following `.gitlab-ci.yml` example:
```yaml
stages:
- test
- build
- deploy
test:
stage: test
script: echo "Running tests"
build:
stage: build
script: echo "Building the app"
2016-11-03 12:29:30 +05:30
2017-08-17 22:00:37 +05:30
deploy_staging:
stage: deploy
script:
- echo "Deploy to staging server"
environment:
name: staging
url: https://staging.example.com
only:
- master
2016-11-03 12:29:30 +05:30
```
2017-08-17 22:00:37 +05:30
We have defined 3 [stages ](yaml/README.md#stages ):
2019-05-18 00:54:41 +05:30
- `test`
- `build`
- `deploy`
2017-08-17 22:00:37 +05:30
The jobs assigned to these stages will run in this order. If a job fails, then
the jobs that are assigned to the next stage won't run, rendering the pipeline
2019-05-18 00:54:41 +05:30
as failed.
In our case:
- The `test` job will run first.
- Then the `build` job.
- Lastly the `deploy_staging` job.
With this configuration, we ensure that:
- The tests pass.
- Our app is able to be built successfully.
- Lastly we deploy to the staging server.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
NOTE: **Note:**
2017-08-17 22:00:37 +05:30
The `environment` keyword is just a hint for GitLab that this job actually
2019-05-18 00:54:41 +05:30
deploys to this environment's `name` . It can also have a `url` that is
exposed in various places within GitLab. Each time a job that
has an environment specified succeeds, a deployment is recorded, storing
2017-08-17 22:00:37 +05:30
the Git SHA and environment name.
2019-05-18 00:54:41 +05:30
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` .
2018-11-20 20:47:30 +05:30
> 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.
2019-05-18 00:54:41 +05:30
2018-11-20 20:47:30 +05:30
> Starting with GitLab 9.3, the environment URL is exposed to the Runner via
> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if
> the URL was not defined there, the external URL from the environment would be
> used.
2017-09-10 17:25:29 +05:30
2019-05-18 00:54:41 +05:30
### Configuring manual deployments
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
Converting automatically executed job into jobs requiring to a manual action involves
adding `when: manual` to the job's configuration.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
The `.gitlab-ci.yml` file for this is as follows:
2017-08-17 22:00:37 +05:30
```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
2016-11-03 12:29:30 +05:30
```
2019-05-18 00:54:41 +05:30
The `when: manual` action:
- Exposes a "play" button in GitLab's UI.
- Means the `deploy_prod` job will only be triggered when the "play" button is clicked.
You can find the "play" button in the pipelines, environments, deployments, and jobs views.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
| 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 ) |
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
Clicking on the play button in any view will trigger the `deploy_prod` job, and the deployment will be recorded under a new
2017-08-17 22:00:37 +05:30
environment named `production` .
2019-05-18 00:54:41 +05:30
NOTE: **Note:**
If your environment's name is `production` (all lowercase),
2017-08-17 22:00:37 +05:30
it will get recorded in [Cycle Analytics ](../user/project/cycle_analytics.md ).
2019-05-18 00:54:41 +05:30
### Configuring dynamic environments
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
Other environments are good for deploying to stable environments like staging or production.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
However, what about environments for branches other than `master` ? Dynamic environments can be used to achieve these.
Dynamic environments make it possible to create environments on the fly by
declaring their names dynamically in `.gitlab-ci.yml` .
Dynamic environments form the basis of [Review apps ](review_apps/index.md ).
#### 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 )
- [Project and group variables ](variables/README.md#variables )
- [`.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
GitLab Runner exposes various [environment variables ](variables/README.md ) when a job runs and so
you can use them as environment names.
In the following example, a job will deploy to all branches except `master` :
2017-08-17 22:00:37 +05:30
```yaml
deploy_review:
stage: deploy
script:
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
only:
- branches
except:
- master
2016-06-22 15:30:34 +05:30
```
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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
use this pattern to distinguish between dynamic environments and the regular ones.
- We tell the job to run [`only` ](yaml/README.md#onlyexcept-basic ) on branches [`except` ](yaml/README.md#onlyexcept-basic ) `master` .
For the value of:
- `environment:name` , the first part is `review` , followed by a `/` and then `$CI_COMMIT_REF_NAME` ,
which takes the value of the branch name.
- `environment:url` , since `$CI_COMMIT_REF_NAME` itself may also contain `/` , or other characters that
would be invalid in a domain name or URL, we use `$CI_ENVIRONMENT_SLUG` so that the environment can get a specific and distinct URL for each branch.
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.
You could also use `$CI_COMMIT_REF_SLUG` in `environment:url` . For example, `https://$CI_COMMIT_REF_SLUG.example.com` .
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. The example
above would give you an URL like `https://100-do-the-thing.example.com` .
NOTE: **Note:**
2017-08-17 22:00:37 +05:30
You are not bound to use the same prefix or only slashes in the dynamic
2019-05-18 00:54:41 +05:30
environments' names (`/`). However, this will enable the [grouping similar environments ](#grouping-similar-environments ) feature.
### 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.
- Finally, manually deployed to the production server.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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.
2017-08-17 22:00:37 +05:30
```yaml
stages:
- test
- build
- deploy
test:
stage: test
script: echo "Running tests"
build:
stage: build
script: echo "Building the app"
deploy_review:
stage: deploy
script:
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
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:
2016-06-22 15:30:34 +05:30
stage: deploy
2017-08-17 22:00:37 +05:30
script:
- echo "Deploy to production server"
environment:
name: production
url: https://example.com
when: manual
only:
- master
2016-06-22 15:30:34 +05:30
```
2017-08-17 22:00:37 +05:30
A more realistic example would include copying files to a location where a
2019-05-18 00:54:41 +05:30
webserver (for example, NGINX) could then read and serve.
The example below will copy the `public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public` :
2016-06-22 15:30:34 +05:30
2017-08-17 22:00:37 +05:30
```yaml
review_app:
stage: deploy
script:
- rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_COMMIT_REF_SLUG.example.com
```
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
This example requires that NGINX and GitLab Runner are set up on the server this job will run on.
NOTE: **Note:**
See the [limitations ](#limitations ) section for some edge cases regarding naming of your branches and Review Apps.
The complete example provides the following workflow for developers:
- Create a branch locally.
- Make changes and commit them
- Push the branch to GitLab.
- Create a merge request.
Behind the scenes, GitLab runner will:
- 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.
- If the build succeeds, the app will be is deployed to an environment with a name specific to the
branch.
So now, every branch:
- Gets its own environment.
- Is deployed to its own location, with the added benefit of:
- Having a [history of deployments ](#viewing-deployment-history ).
- Being able to [rollback changes ](#retrying-and-rolling-back ) if needed.
For more information on using the URL, see [Using the environment URL ](#using-the-environment-url ).
### Protected environments
Environments can be "protected", restricting access to them.
For more information, see [Protected environments ](environments/protected_environments.md ).
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
## Working with environments
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
Having configured environments, GitLab provides many features to work with them. These are documented below.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
### Viewing environments and deployments
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
A list of environments and deployment statuses is available on project's **Operations > Environments** page.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
For example:
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
![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.
- The commit information of the last deployment such as who committed, to what
branch, and the Git SHA of the commit.
- The exact time the last deployment was performed.
- A button that takes you to the URL that you have defined under the
`environment` keyword in `.gitlab-ci.yml` .
- A button that re-deploys the latest deployment, meaning it runs the job
defined by the environment name for that specific commit.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
The information shown in the **Environments** page is limited to the latest
deployments, but an environment can have multiple deployments.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
> **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.
> - The environments page can only be viewed by Reporters and above. For more
> information on the permissions, see the [permissions documentation](../user/permissions.md).
> - 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.
- Can have the full history of your deployments per every environment.
Clicking on an environment shows the history of its deployments. Here's an example **Environments** page
with multiple deployments:
![Deployments ](img/deployments_view.png )
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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 ).
### Retrying and rolling back
If there is a problem with a deployment, you can retry it or roll it back.
To retry or rollback a deployment:
1. Navigate to **Operations > Environments** .
1. Click on the environment.
1. On the page that lists the deployment history for the environment, click the:
- **Rollback** button against a previously successful deployment, to roll back to that deployment.
- **Retry** button against the last deployment, to retry that deployment.
NOTE: **Note:**
The defined deployment process in the job's `script` determines whether the rollback succeeds or not.
### Using the environment URL
The [environment URL ](yaml/README.md#environmenturl ) is exposed in a few
2018-03-17 18:26:18 +05:30
places within GitLab.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
These are:
- 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 )
You can see this information in a merge request itself if:
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
- 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:
2017-08-17 22:00:37 +05:30
![Environment URLs in merge request ](img/environments_link_url_mr.png )
2019-05-18 00:54:41 +05:30
#### Going from source files to public pages
2017-08-17 22:00:37 +05:30
2019-03-02 22:35:43 +05:30
With GitLab's [Route Maps ](review_apps/index.md#route-maps ) you can go directly
from source files to public pages on the environment set for Review Apps.
2016-06-22 15:30:34 +05:30
2019-05-18 00:54:41 +05:30
### Stopping an environment
Stopping an environment:
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
- Moves it from the list of **Available** environments to the list of **Stopped** environments on the [**Environments** page ](#viewing-environments-and-deployments ).
- Executes an [`on_stop` action ](yaml/README.md#environmenton_stop ), if defined.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
NOTE: **Note:**
Starting with GitLab 8.14, dynamic environments will be stopped automatically
when their associated branch is deleted.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
#### Automatically stopping an environment
Environments can be stopped automatically using special configuration.
2017-08-17 22:00:37 +05:30
Consider the following example where the `deploy_review` calls the `stop_review`
to clean up and stop the environment:
```yaml
deploy_review:
stage: deploy
script:
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_NAME
url: https://$CI_ENVIRONMENT_SLUG.example.com
on_stop: stop_review
only:
- branches
except:
- master
stop_review:
stage: deploy
variables:
GIT_STRATEGY: none
script:
- echo "Remove review app"
when: manual
environment:
name: review/$CI_COMMIT_REF_NAME
action: stop
```
2019-05-18 00:54:41 +05:30
Setting the [`GIT_STRATEGY` ](yaml/README.md#git-strategy ) to `none` is necessary on the
`stop_review` job so that the [GitLab Runner ](https://docs.gitlab.com/runner/ ) won't try to check out the code
2017-08-17 22:00:37 +05:30
after the branch is deleted.
2016-06-22 15:30:34 +05:30
2017-08-17 22:00:37 +05:30
When you have an environment that has a stop action defined (typically when
2019-05-18 00:54:41 +05:30
the environment describes a Review App), GitLab will automatically trigger a
2017-08-17 22:00:37 +05:30
stop action when the associated branch is deleted. The `stop_review` job must
be in the same `stage` as the `deploy_review` one in order for the environment
to automatically stop.
2019-05-18 00:54:41 +05:30
You can read more in the [`.gitlab-ci.yml` reference ](yaml/README.md#environmenton_stop ).
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
### Grouping similar environments
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015) in GitLab 8.14.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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.
2017-08-17 22:00:37 +05:30
In short, environments that are named like `type/foo` are presented under a
group named `type` .
2019-05-18 00:54:41 +05:30
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:
2017-08-17 22:00:37 +05:30
```yaml
deploy_review:
stage: deploy
script:
- echo "Deploy a review app"
environment:
name: review/$CI_COMMIT_REF_NAME
```
2019-05-18 00:54:41 +05:30
In this case, if you visit the **Environments** page and the branches
2017-08-17 22:00:37 +05:30
exist, you should see something like:
![Environment groups ](img/environments_dynamic_groups.png )
2019-05-18 00:54:41 +05:30
### Monitoring environments
2017-08-17 22:00:37 +05:30
2018-11-20 20:47:30 +05:30
> **Notes:**
2017-08-17 22:00:37 +05:30
>
2018-11-20 20:47:30 +05:30
> - For the monitoring dashboard to appear, you need to:
2019-05-18 00:54:41 +05:30
> - Enable the [Prometheus integration](../user/project/integrations/prometheus.md).
> - Configure Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md)
> - With GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
If you have enabled [Prometheus for monitoring system and response metrics ](../user/project/integrations/prometheus.md ), you can monitor the performance behavior of your app running in each environment.
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
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
successfully retrieved, a **Monitoring** button will appear for each environment.
2017-08-17 22:00:37 +05:30
2018-03-17 18:26:18 +05:30
![Environment Detail with Metrics ](img/deployments_view.png )
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
Clicking on the **Monitoring** button will display a new page showing up to the last
2017-08-17 22:00:37 +05:30
8 hours of performance data. It may take a minute or two for data to appear
after initial deployment.
2019-05-18 00:54:41 +05:30
All deployments to an environment are shown directly on the monitoring dashboard,
2017-08-17 22:00:37 +05:30
which allows easy correlation between any changes in performance and a new
version of the app, all without leaving GitLab.
![Monitoring dashboard ](img/environments_monitoring.png )
2019-05-18 00:54:41 +05:30
### Web terminals
2018-03-17 18:26:18 +05:30
2019-05-18 00:54:41 +05:30
> Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners.
2018-03-17 18:26:18 +05:30
2019-05-18 00:54:41 +05:30
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.
This is a powerful feature that allows you to debug issues without leaving the comfort of your web browser. To
2018-03-17 18:26:18 +05:30
enable it, just follow the instructions given in the service integration
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 )
2019-05-18 00:54:41 +05:30
This works just like any other terminal. You'll be in the container created
by your deployment so you can:
2018-03-17 18:26:18 +05:30
2019-05-18 00:54:41 +05:30
- Run shell commands and get responses in real time.
- Check the logs.
- Try out configuration or code tweaks etc.
2018-03-17 18:26:18 +05:30
2019-05-18 00:54:41 +05:30
You can open multiple terminals to the same environment, they each get their own shell
session and even a multiplexer like `screen` or `tmux` .
2018-03-17 18:26:18 +05:30
2019-05-18 00:54:41 +05:30
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.
2018-03-17 18:26:18 +05:30
2019-05-18 00:54:41 +05:30
### Check out deployments locally
2017-08-17 22:00:37 +05:30
2019-05-18 00:54:41 +05:30
Since GitLab 8.13, a reference in the Git repository is saved for each deployment, so
2017-08-17 22:00:37 +05:30
knowing the state of your current environments is only a `git fetch` away.
2019-05-18 00:54:41 +05:30
In your Git configuration, append the `[remote "<your-remote>"]` block with an extra
2017-08-17 22:00:37 +05:30
fetch line:
2019-05-18 00:54:41 +05:30
```text
2017-08-17 22:00:37 +05:30
fetch = +refs/environments/*:refs/remotes/origin/environments/*
```
2019-05-18 00:54:41 +05:30
### Scoping environments with specs **[PREMIUM]**
Some GitLab [Enterprise Edition ](https://about.gitlab.com/pricing/ ) features can behave differently for each
environment. For example, you can [create a secret variable to be injected only into a production environment ](https://docs.gitlab.com/ee/ci/variables/#limiting-environment-scopes-of-environment-variables-premium ).
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,
such as [Review apps ](review_apps/index.md ) (`review/*`).
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.
2017-08-17 22:00:37 +05:30
## Limitations
2019-05-18 00:54:41 +05:30
You are limited to use only the [CI predefined variables ](variables/README.md ) in the
`environment: name` . If you try to re-use variables defined inside `script`
as part of the environment name, it will not work.
2017-08-17 22:00:37 +05:30
## 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/ )
- [Review Apps - Use dynamic environments to deploy your code for every branch ](review_apps/index.md )