diff options
| author | Evan Read <eread@gitlab.com> | 2019-03-21 16:06:24 +1000 |
|---|---|---|
| committer | Evan Read <eread@gitlab.com> | 2019-03-26 12:49:24 +1000 |
| commit | e2d4615a3ee8b62ded9f863596e4a85e417b1942 (patch) | |
| tree | d867953d68c844f4ea3baadb3bea82fc582d789c /doc | |
| parent | 66054aeb13315ccf99f167081d09b7be75be3e46 (diff) | |
| download | gitlab-ce-e2d4615a3ee8b62ded9f863596e4a85e417b1942.tar.gz | |
Refactor and restructure environments page
- Groups content into relevant sections.
- Content edited.
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/ci/README.md | 43 | ||||
| -rw-r--r-- | doc/ci/environments.md | 683 | ||||
| -rw-r--r-- | doc/ci/environments/protected_environments.md | 48 |
3 files changed, 452 insertions, 322 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md index 47810a8b7b6..5fe6c78701c 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -43,28 +43,27 @@ For complete control, you can manually configure GitLab CI/CD. With basic knowledge of how GitLab CI/CD works, the following documentation extends your knowledge into more features: -| Topic | Description | -|:--------------------------------------------------------------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------| -| [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. | -| [Configuring GitLab Runners](runners/README.md) | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/). | -| [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. | +| Topic | Description | +|:--------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------| +| [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. | +| [Configuring GitLab Runners](runners/README.md) | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/). | +| [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. | ### GitLab Pages diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 05d392d54cb..bcd6f6eb1cb 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -1,45 +1,65 @@ -# Introduction to environments and deployments +# Environments and deployments > Introduced in GitLab 8.9. -During the development of software, there can be many stages until it's ready -for public consumption. You sure want to first test your code and then deploy it -in a testing or staging environment before you release it to the public. That -way you can prevent bugs not only in your software, but in the deployment -process as well. +Environments allow control of the continuous deployment of your software, +all within GitLab. -GitLab CI is capable of not only testing or building your projects, but also +## 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 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. -## Overview +It's important to know that: -With environments, you can control the Continuous Deployment of your software -all within GitLab. All you need to do is define them in your project's -[`.gitlab-ci.yml`][yaml] as we will explore below. GitLab provides a full -history of your deployments per every environment. +- 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. -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. GitLab 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][kube] +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) enabled for your project, you can use it to assist with your deployments, and can even access a [web terminal](#web-terminals) for your environment from within GitLab! -To better understand how environments and deployments work, let's consider an -example. We assume that you have already created a project in GitLab and set up -a Runner. The example will cover the following: +## 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: -- 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 +- Created a [project](../gitlab-basics/create-project.md) in GitLab. +- Set up [a Runner](runners/README.md). -Let's see how it all ties together. +In the scenario: -## Defining environments +- 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 Let's consider the following `.gitlab-ci.yml` example: @@ -70,123 +90,64 @@ deploy_staging: We have defined 3 [stages](yaml/README.md#stages): -- test -- build -- deploy +- `test` +- `build` +- `deploy` 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 -as failed. In our case, the `test` job will run first, then the `build` and -lastly the `deploy_staging`. With this, we ensure that first the tests pass, -then our app is able to be built successfully, and lastly we deploy to the -staging server. +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. +NOTE: **Note:** The `environment` keyword is just a hint for GitLab that this job actually -deploys to this environment's `name`. It can also have a `url` which, as we -will later see, is exposed in various places within GitLab. Each time a job that -has an environment specified and succeeds, a deployment is recorded, remembering +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 the Git SHA and environment name. -> **Note:** +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`. + > 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. -> -> **Note:** + > 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. -To sum up, with the above `.gitlab-ci.yml` we have achieved that: - -- 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 to deploy to the staging server -- When a merge request is merged, all jobs will run and the `deploy_staging` - in particular will deploy our code to a staging server while the deployment - will be recorded in an environment named `staging`. - -Let's now see how that information is exposed within GitLab. +### Configuring manual deployments -## Viewing the current status of an environment +Converting automatically executed job into jobs requiring to a manual action involves +adding `when: manual` to the job's configuration. -The environment list under your project's **Operations > Environments**, is -where you can find information of the last deployment status of an environment. +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. -Here's how the Environments page looks so far. - - - -There's a bunch of information there, specifically you can see: - -- 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 - -> **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][permissions]. -> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured -> will show up in the "Environment" and "Last deployment" lists. - -The information shown in the Environments page is limited to the latest -deployments, but as you may have guessed an environment can have multiple -deployments. - -## Viewing the deployment history of an environment - -GitLab keeps track of your deployments, so you always know what is currently -being deployed on your servers. That way you can have the full history of your -deployments per every environment right in your browser. Clicking on an -environment will show the history of its deployments. Assuming you have deployed -multiple times already, here's how a specific environment's page looks like. - - - -We can see the same information as when in the Environments page, but this time -all deployments are shown. As you may have noticed, apart from the **Re-deploy** -button there are now **Rollback** buttons for each deployment. Let's see how -that works. - -## Rolling back changes - -You can't control everything, so sometimes things go wrong. When that unfortunate -time comes GitLab has you covered. Simply by clicking the **Rollback** button -that can be found in the deployments page -(**Operations > Environments > `environment name`**) you can relaunch the -job with the commit associated with it. - ->**Note:** -Bear in mind that your mileage will vary and it's entirely up to how you define -the deployment process in the job's `script` whether the rollback succeeds or not. -GitLab CI is just following orders. - -Thankfully that was the staging server that we had to rollback, and since we -learn from our mistakes, we decided to not make the same again when we deploy -to the production server. Enter manual actions for deployments. - -## Manually deploying to environments - -Turning a job from running automatically to a manual action is as simple as -adding `when: manual` to it. To expand on our previous example, let's add -another job that this time deploys our app to a production server and is -tracked by a `production` environment. The `.gitlab-ci.yml` looks like this -so far: +The `.gitlab-ci.yml` file for this is as follows: ```yaml stages: @@ -224,41 +185,62 @@ deploy_prod: - master ``` -The `when: manual` action exposes a play button in GitLab's UI and the -`deploy_prod` job will only be triggered if and when we click that play button. -You can find it in the pipeline, job, environment, and deployment views. +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. -| Pipelines | Single pipeline | Environments | Deployments | jobs | -| --------- | ----------------| ------------ | ----------- | -------| -|  |  |  |  |  | +You can find the "play" button in the pipelines, environments, deployments, and jobs views. -Clicking on the play button in either of these places will trigger the -`deploy_prod` job, and the deployment will be recorded under a new +| View | Screenshot | +|:----------------|:-------------------------------------------------------------------------------| +| Pipelines |  | +| Single pipeline |  | +| Environments |  | +| Deployments |  | +| Jobs |  | + +Clicking on the play button in any view will trigger the `deploy_prod` job, and the deployment will be recorded under a new environment named `production`. ->**Note:** -Remember that if your environment's name is `production` (all lowercase), then +NOTE: **Note:** +If your environment's name is `production` (all lowercase), it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md). -Double the benefit! -## Dynamic environments +### Configuring 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). +Other environments are good for deploying to stable environments like staging or production. -NOTE: **Note:** -The `name` and `url` parameters can use most of the CI/CD variables, -including [predefined](variables/README.md#predefined-environment-variables), -[project/group ones](variables/README.md#variables) and -[`.gitlab-ci.yml` variables](yaml/README.md#variables). You however cannot use variables -defined under `script` or on the Runner's side. There are also other variables that -are unsupported in the context of `environment:name`. You can read more about -[where variables can be used](variables/where_variables_can_be_used.md). - -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`: +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`: ```yaml deploy_review: @@ -274,39 +256,49 @@ deploy_review: - master ``` -Let's break it down in pieces. The job's name is `deploy_review` and it runs -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 -`environment:name` being `review/$CI_COMMIT_REF_NAME`. Now that's an interesting -one. Since the [environment name][env-name] can contain slashes (`/`), we can -use this pattern to distinguish between dynamic environments and the regular -ones. - -So, the first part is `review`, followed by a `/` and then `$CI_COMMIT_REF_NAME` -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 -URL, we use `$CI_ENVIRONMENT_SLUG` in the `environment:url` so that the -environment can get a specific and distinct URL for each branch. In this case, -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`, e.g.: -`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 -[GitLab Flow][gitlab-flow], collisions are very 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` - -Last but not least, we tell the job to run [`only`](yaml/README.md#onlyexcept-basic) on branches -[`except`](yaml/README.md#onlyexcept-basic) master. - ->**Note:** +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:** 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. + +For example: + + + +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. + +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 | -| -------------------- | ------------ | ----------- | -|  |  |  | +These are: + +- In a merge request widget as a link: +  +- In the Environments view as a button: +  +- In the Deployments view as a button: +  -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. +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`). + +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. +- Removes it from the list of 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 +544,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 +579,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 exist, you should see something like:  -## Monitoring environments +### Monitoring environments > **Notes:** > > - 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 version of the app, all without leaving GitLab.  -## Web terminals +### Web terminals + +> Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners. ->**Note:** -Web terminals were added in GitLab 8.15 and are only available to project -maintainers and owners. +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. -If you deploy to your environments with the help of a deployment service (e.g., -the [Kubernetes integration][kube]), 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 +This is a 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 integration documentation. @@ -568,41 +636,71 @@ establish the terminal session:  -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`! +This works just like any other terminal. You'll be in the container created +by your deployment so you can: ->**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. +- 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`. -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. +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. -## Checkout deployments locally +### Check out deployments locally -Since 8.13, a reference in the git repository is saved for each deployment, so +Since GitLab 8.13, a reference in the Git repository is saved for each deployment, so knowing the state of your current environments is only a `git fetch` away. -In your git config, append the `[remote "<your-remote>"]` block with an extra +In your Git configuration, append the `[remote "<your-remote>"]` block with an extra fetch line: -``` +```text fetch = +refs/environments/*:refs/remotes/origin/environments/* ``` +### 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](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: + +| 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. + ## Limitations -1. You are limited to use only the [CI predefined variables][variables] in the - `environment: name`. If you try to re-use variables defined inside `script` - as part of the environment name, it will not work. +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. ## Further reading @@ -611,18 +709,3 @@ 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) - -[Pipelines]: pipelines.md -[yaml]: yaml/README.md -[environments]: #environments -[deployments]: #deployments -[permissions]: ../user/permissions.md -[variables]: variables/README.md -[env-name]: yaml/README.md#environmentname -[onstop]: yaml/README.md#environmenton_stop -[ce-7015]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015 -[gitlab-flow]: ../workflow/gitlab_flow.md -[gitlab runner]: https://docs.gitlab.com/runner/ -[git-strategy]: yaml/README.md#git-strategy -[kube]: ../user/project/clusters/index.md -[prom]: ../user/project/integrations/prometheus.md diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md new file mode 100644 index 00000000000..219af4ced9d --- /dev/null +++ b/doc/ci/environments/protected_environments.md @@ -0,0 +1,48 @@ +# Protected Environments **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. + +## Overview + +[Environments](../environments.md) can be used for different reasons: + +- Some of them are just for testing. +- Others are for production. + +Because deploy jobs can be raised by different users with different roles, it is important that +specific environments are "protected" to avoid unauthorized people affecting them. + +By default, a protected environment does one thing: it ensures that only people +with the right privileges can deploy to it, thus keeping it safe. + +NOTE: **Note**: +A GitLab admin is always allowed to use environments, even if they are protected. + +To protect, update, or unprotect an environment, you need to have at least +[Maintainer permissions](../../user/permissions.md). + +## Protecting environments + +To protect an environment: + +1. Navigate to your project's **Settings > CI/CD**. +1. Expand the **Protected Environments** section. +1. From the **Environment** dropdown menu, select the environment you want to protect. +1. In the **Allowed to Deploy** dropdown menu, select the role, users, or groups you want to have deploy access. + There are some considerations to have in mind: + - There are two roles to choose from: + - **Maintainers**: will allow access to all maintainers in the project. + - **Developers**: will allow access to all maintainers and all developers in the project. + - You can only select groups that are associated with the project. + - Only users that have at least Developer permission level will appear on + the **Allowed to Deploy** dropdown menu. +1. Click the **Protect** button. + +The protected environment will now appear in the list of protected environments. + +## Modifying and unprotecting environments + +Maintainers can: + +- Update existing protected environments at any time by changing the access on **Allowed to deploy** dropdown menu. +- Unprotect a protected environment by clicking the **Unprotect** button of the environment to unprotect. |