| [Creating and using CI/CD pipelines](pipelines.md) | Understand, visualize, create, and use CI/CD pipelines. |
| [CI/CD Variables](variables/README.md) | How environment variables can be configured and made available in pipelines. |
| [Where variables can be used](variables/where_variables_can_be_used.md) | A deeper look into where and how CI/CD variables can be used. |
| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions | Learn about the access levels a user can have for performing certain CI actions. |
| [Introduction to environments and deployments](environments.md) | Learn how to separate your jobs into environments and use them for different purposes like testing, building and, deploying. |
| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Learn about the output of jobs. |
| [Cache dependencies in GitLab CI/CD](caching/index.md) | Discover how to speed up pipelines using caching. |
| [Using Git submodules with GitLab CI](git_submodules.md) | How to run your CI jobs when using Git submodules. |
| [Pipelines for merge requests](merge_request_pipelines/index.md) | Create pipelines specifically for merge requests. |
| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md) | Use SSH keys in your build environment. |
| [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. |
| [Pipeline schedules](../user/project/pipelines/schedules.md) | Trigger pipelines on a schedule. |
| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. |
| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. |
| [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. |
| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes in a per-branch basis. |
| [Deploy Boards](../user/project/deploy_boards.md)**[PREMIUM]** | Check the current health and status of each CI/CD environment running on Kubernetes. |
| [GitLab CI/CD for external repositories](ci_cd_for_external_repos/index.md)**[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
| [Protected environments](environments/protected_environments.md)**[PREMIUM]** | Ensure that only people with the right privileges can deploy to an environment. |
| [Creating and using CI/CD pipelines](pipelines.md) | Understand, visualize, create, and use CI/CD pipelines. |
| [CI/CD Variables](variables/README.md) | How environment variables can be configured and made available in pipelines. |
| [Where variables can be used](variables/where_variables_can_be_used.md) | A deeper look into where and how CI/CD variables can be used. |
| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions | Learn about the access levels a user can have for performing certain CI actions. |
| [Environments and deployments](environments.md) | Deploy the output of jobs into environments for reviewing, staging, and production. |
| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Learn about the output of jobs. |
| [Cache dependencies in GitLab CI/CD](caching/index.md) | Discover how to speed up pipelines using caching. |
| [Using Git submodules with GitLab CI](git_submodules.md) | How to run your CI jobs when using Git submodules. |
| [Pipelines for merge requests](merge_request_pipelines/index.md) | Create pipelines specifically for merge requests. |
| [Using SSH keys with GitLab CI/CD](ssh_keys/README.md) | Use SSH keys in your build environment. |
| [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. |
| [Pipeline schedules](../user/project/pipelines/schedules.md) | Trigger pipelines on a schedule. |
| [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. |
| [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. |
| [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. |
| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes in a per-branch basis. |
| [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html)**[PREMIUM]** | Check the current health and status of each CI/CD environment running on Kubernetes. |
| [GitLab CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html)**[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. |
- 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:**
You are not bound to use the same prefix or only slashes in the dynamic
environments' names (`/`), but as we will see later, this will enable the
[grouping similar environments](#grouping-similar-environments) feature.
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:
The whole `.gitlab-ci.yml` looks like this so far:
- 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.
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.
```yaml
stages:
...
...
@@ -357,8 +349,9 @@ deploy_prod:
```
A more realistic example would include copying files to a location where a
webserver (NGINX) could then read and serve. The example below will copy the
`public` directory to `/srv/nginx/$CI_COMMIT_REF_SLUG/public`:
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`:
```yaml
review_app:
...
...
@@ -370,76 +363,155 @@ review_app:
url:https://$CI_COMMIT_REF_SLUG.example.com
```
It is assumed that the user has already set up NGINX and GitLab Runner in the
server this job will run on.
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.
>**Note:**
Be sure to check out the [limitations](#limitations) section for some edge
cases regarding naming of your branches and Review Apps.
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.
The development workflow would now be:
For more information on using the URL, see [Using the environment URL](#using-the-environment-url).
- Developer creates a branch locally
- Developer makes changes, commits and pushes the branch to GitLab
- Developer creates a merge request
### Protected environments
Behind the scenes:
Environments can be "protected", restricting access to them.
- GitLab Runner picks up the changes and starts running the jobs
- The jobs run sequentially as defined in `stages`
- First, the tests pass
- Then, the job begins and successfully also passes
- Lastly, the app is deployed to an environment with a name specific to the
branch
For more information, see [Protected environments](environments/protected_environments.md).
So now, every branch gets its own environment and is deployed to its own place
with the added benefit of having a [history of deployments](#viewing-the-deployment-history-of-an-environment)
and also being able to [rollback changes](#rolling-back-changes) if needed.
Let's briefly see where URL that's defined in the environments is exposed.
## Working with environments
## Making use of the environment URL
Having configured environments, GitLab provides many features to work with them. These are documented below.
### Viewing environments and deployments
A list of environments and deployment statuses is available on project's **Operations > Environments** page.
|  |  |  |
These are:
- In a merge request widget as a link:
- In the Environments view as a button:
- In the Deployments view as a button:
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`).
If a merge request is eventually merged to the default branch (in our case
`master`) and that branch also deploys to an environment (in our case `staging`
and/or `production`) you can see this information in the merge request itself.
For example:
### Go directly from source files to public pages on the environment
#### Going from source files to public pages
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.
From then on, you have a full development cycle, where your app is tested, built, deployed
as a Review App, deployed to a staging server once the merge request is merged,
and finally manually deployed to the production server. This is a simple workflow,
but when you have multiple developers working on a project
at the same time, each of them pushing to their own branches, dynamic environments are
created all the time. In which case, you probably want to do some clean up. Read
next how environments can be stopped.
### Stopping an environment
## Stopping an environment
Stopping an environment:
By stopping an environment, you are effectively terminating its recording of the
deployments that happen in it.
- 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.
A branch is associated with an environment when the CI pipeline that is created
for this branch, was recently deployed to this environment. You can think of
the CI pipeline as the glue between the branch and the environment:
`branch ➔ CI pipeline ➔ environment`.
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.
There is a special case where environments can be manually stopped. That can
happen if you provide another job for that matter. The syntax is a little
tricky since a job calls another job to do the job.
NOTE: **Note:**
Starting with GitLab 8.14, dynamic environments will be stopped automatically
when their associated branch is deleted.
#### Automatically stopping an environment
Environments can be stopped automatically using special configuration.
Consider the following example where the `deploy_review` calls the `stop_review`
to clean up and stop the environment:
...
...
@@ -470,35 +542,31 @@ stop_review:
action:stop
```
Setting the [`GIT_STRATEGY`][git-strategy] to `none` is necessary on the
`stop_review` job so that the [GitLab Runner] won't try to checkout the code
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
after the branch is deleted.
>**Note:**
Starting with GitLab 8.14, dynamic environments will be stopped automatically
when their associated branch is deleted.
When you have an environment that has a stop action defined (typically when
the environment describes a review app), GitLab will automatically trigger a
the environment describes a Review App), GitLab will automatically trigger a
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.
You can read more in the [`.gitlab-ci.yml` reference][onstop].
You can read more in the [`.gitlab-ci.yml` reference](yaml/README.md#environmenton_stop).
## Grouping similar environments
### Grouping similar environments
> [Introduced][ce-7015] in GitLab 8.14.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015) in GitLab 8.14.
As we've seen in the [dynamic environments](#dynamic-environments), you can
prepend their name with a word, then followed by a `/` and finally the branch
name which is automatically defined by the `CI_COMMIT_REF_NAME` variable.
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.
In short, environments that are named like `type/foo` are presented under a
group named `type`.
In our minimal example, we name the environments `review/$CI_COMMIT_REF_NAME`
where `$CI_COMMIT_REF_NAME` is the branch name:
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:
```yaml
deploy_review:
...
...
@@ -509,49 +577,47 @@ deploy_review:
name:review/$CI_COMMIT_REF_NAME
```
In that case, if you visit the Environments page, and provided the branches
In this case, if you visit the **Environments** page and the branches
> - For the monitoring dashboard to appear, you need to:
> - Have enabled the [Prometheus integration][prom]
> - Configured 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
> - 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.
If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment.
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.
Once configured, GitLab will attempt to retrieve [supported performance metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus_library/index.html) for any
environment which has had a successful deployment. If monitoring data was
successfully retrieved, a Monitoring button will appear for each environment.
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.
Clicking on the Monitoring button will display a new page, showing up to the last
Clicking on the **Monitoring** button will display a new page showing up to the last
8 hours of performance data. It may take a minute or two for data to appear
after initial deployment.
All deployments to an environment are shown directly on the monitoring dashboard
All deployments to an environment are shown directly on the monitoring dashboard,
which allows easy correlation between any changes in performance and a new
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](variables/README.md#limiting-environment-scopes-of-variables-premium).
Some GitLab [Enterprise Edition](https://about.gitlab.com/pricing/) features can behave differently for each [Environment](#introduction-to-environments-and-deployments).
For example, you can [create a secret variable to be injected only into a production environment](variables/README.md#limiting-environment-scopes-of-variables-premium).
In most cases, these features use the _environment specs_ mechanism, which offers
an efficient way to implement scoping within each environment group.
...
...
@@ -614,13 +678,13 @@ Let's say there are four environments:
Each environment can be matched with the following environment spec:
