| [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](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. |
| [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. |
| [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:
- 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 whole `.gitlab-ci.yml` looks like this so far:
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,157 @@ 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.
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).
## Working with environments
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.
- 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:**
Be sure to check out the [limitations](#limitations) section for some edge
cases regarding naming of your branches and Review Apps.
Clicking on an environment shows the history of its deployments. Here's an example **Environments** page
with multiple deployments:
---
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
- Developer makes changes, commits and pushes the branch to GitLab
- Developer creates a merge request
If there is a problem with a deployment, you can retry it or roll it back.
Behind the scenes:
To retry or rollback a deployment:
- 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
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.
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.
NOTE: **Note:**
The defined deployment process in the job's `script` determines whether the rollback succeeds or not.
## 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
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:
> - 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).
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:
