| [Creating and using CI/CD pipelines](pipelines.md) | Understand, visualize, create, and use CI/CD pipelines. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [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. |
| [Protected environments](https://docs.gitlab.com/ce/ci/environments/protected_environments.html)**[PREMIUM]** | Ensure that only people with the right privileges can deploy to an environment. |
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`:
```yaml
```yaml
deploy_review:
deploy_review:
...
@@ -274,39 +256,49 @@ deploy_review:
...
@@ -274,39 +256,49 @@ deploy_review:
-master
-master
```
```
Let's break it down in pieces. The job's name is `deploy_review` and it runs
In this example:
on the `deploy` stage. The `script` at this point is fictional, you'd have to
use your own based on your deployment. Then, we set the `environment` with the
- The job's name is `deploy_review` and it runs on the `deploy` stage.
`environment:name` being `review/$CI_COMMIT_REF_NAME`. Now that's an interesting
- We set the `environment` with the `environment:name` as `review/$CI_COMMIT_REF_NAME`.
one. Since the [environment name][env-name] can contain slashes (`/`), we can
Since the [environment name](yaml/README.md#environmentname) can contain slashes (`/`), we can
use this pattern to distinguish between dynamic environments and the regular
use this pattern to distinguish between dynamic environments and the regular ones.
ones.
- We tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches [`except`](yaml/README.md#onlyexcept-basic)`master`.
So, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`
For the value of:
which takes the value of the branch name. Since `$CI_COMMIT_REF_NAME` itself may
also contain `/`, or other characters that would be invalid in a domain name or
-`environment:name`, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME`,
URL, we use `$CI_ENVIRONMENT_SLUG` in the `environment:url` so that the
which takes the value of the branch name.
environment can get a specific and distinct URL for each branch. In this case,
-`environment:url`, since `$CI_COMMIT_REF_NAME` itself may also contain `/`, or other characters that
given a `$CI_COMMIT_REF_NAME` of `100-Do-The-Thing`, the URL will be something
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.
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.
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
You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`, e.g.:
the web server to serve these requests is based on your setup.
`https://$CI_COMMIT_REF_SLUG.example.com`. We use `$CI_ENVIRONMENT_SLUG`
here because it is guaranteed to be unique, but if you're using a workflow like
You could also use `$CI_COMMIT_REF_SLUG` in `environment:url`. For example, `https://$CI_COMMIT_REF_SLUG.example.com`.
[GitLab Flow][gitlab-flow], collisions are very unlikely, and you may prefer
We have used `$CI_ENVIRONMENT_SLUG` here because it is guaranteed to be unique. If you're using a workflow like
environment names to be more closely based on the branch name - the example
[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`
above would give you an URL like `https://100-do-the-thing.example.com`.
Last but not least, we tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches
- 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.
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.
> - 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.
>**Note:**
Clicking on an environment shows the history of its deployments. Here's an example **Environments** page
Be sure to check out the [limitations](#limitations) section for some edge
with multiple deployments:
cases regarding naming of your branches and Review Apps.
---
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).
The development workflow would now be:
### Retrying and rolling back
- Developer creates a branch locally
If there is a problem with a deployment, you can retry it or roll it back.
- Developer makes changes, commits and pushes the branch to GitLab
- Developer creates a merge request
Behind the scenes:
To retry or rollback a deployment:
- GitLab Runner picks up the changes and starts running the jobs
1. Navigate to **Operations > Environments**.
- The jobs run sequentially as defined in `stages`
1. Click on the environment.
- First, the tests pass
1. On the page that lists the deployment history for the environment, click the:
- Then, the job begins and successfully also passes
-**Rollback** button against a previously successful deployment, to roll back to that deployment.
- Lastly, the app is deployed to an environment with a name specific to the
-**Retry** button against the last deployment, to retry that deployment.
branch
So now, every branch gets its own environment and is deployed to its own place
NOTE: **Note:**
with the added benefit of having a [history of deployments](#viewing-the-deployment-history-of-an-environment)
The defined deployment process in the job's `script` determines whether the rollback succeeds or not.
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.
## Making use of the environment URL
To avoid failed deployments being deployed in a production environment, [configure manual actions](#configing-manual-deployments) for production deployments.
### Using the environment URL
The [environment URL](yaml/README.md#environmenturl) is exposed in a few
The [environment URL](yaml/README.md#environmenturl) is exposed in a few
places within GitLab.
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 |
> - For the monitoring dashboard to appear, you need to:
> - For the monitoring dashboard to appear, you need to:
> - Have enabled the [Prometheus integration][prom]
> - Enable the [Prometheus integration](../user/project/integrations/prometheus.md).
> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.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
> - With GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
> 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
Once configured, GitLab will attempt to retrieve [supported performance metrics](../user/project/integrations/prometheus_library/index.md) for any
environment which has had a successful deployment. If monitoring data was
environment that has had a successful deployment. If monitoring data was
successfully retrieved, a Monitoring button will appear for each environment.
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
8 hours of performance data. It may take a minute or two for data to appear
after initial deployment.
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
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).
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:
