From 6715091bbc035142237f5121623bb0b84c3def51 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 19 Oct 2016 11:54:38 +0200 Subject: WIP refactor environments --- doc/ci/environments.md | 159 +++++++++++++++++++++++++++++++-------- doc/ci/img/deployments_view.png | Bin 0 -> 179909 bytes doc/ci/img/environments_view.png | Bin 0 -> 57534 bytes doc/ci/yaml/README.md | 62 ++++++++++++++- doc/user/permissions.md | 4 +- 5 files changed, 190 insertions(+), 35 deletions(-) create mode 100644 doc/ci/img/deployments_view.png create mode 100644 doc/ci/img/environments_view.png diff --git a/doc/ci/environments.md b/doc/ci/environments.md index e070302fb82..9d65621fbbb 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -3,69 +3,166 @@ >**Note:** Introduced in GitLab 8.9. -## Environments +During the development of a software there can be many stages until it's ready +for public consumption. You sure want to first see your code 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. + +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]. + +In the following sections, we'll see how that works. + +## An environments example + +Let's assume that you have + +1. Define the environments in `.gitlab-ci.yml` +1. Push the repository to GitLab +1. Runner picks up the job +1. The job finishes successfully +1. The environments get created if they don't already exist +1. A deployment is recorded remembering the environment name and the Git SHA of + the last commit of the pipeline + +Further runs of the CI will + +Actions + +View environments +View deployments + Rollback deployments + Run deployments +View link to environment URL +View last commit message of deployment +View person who performed the deployment +View commit SHA that triggered the deployment +View branch the deployment was based on +View time ago the deployment was performed + +Environments are like tags for your CI jobs, describing where code gets deployed. + +You can think of names such as testing, staging or production. -Environments are places where code gets deployed, such as staging or production. CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. + Defining environments in a project's `.gitlab-ci.yml` lets developers track [deployments] to these environments. -## Deployments +The environments page can only be viewed by Reporters and above. For more +information on the permissions, see the [permissions documentation][permissions]. -Deployments are created when [jobs] deploy versions of code to [environments]. +### Defining environments -### Checkout deployments locally +While you can create and delete 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. -Since 8.13, a reference in the git repository is saved for each deployment. So -knowing what the state is of your current environments is only a `git fetch` -away. +The `environment` keyword is just a hint for GitLab that this job actually +deploys to this environment. Each time the job succeeds, a deployment is +recorded, remembering the Git SHA and environment name. -In your git config, append the `[remote ""]` block with an extra -fetch line: +Add something like this to your `.gitlab-ci.yml`: ``` -fetch = +refs/environments/*:refs/remotes/origin/environments/* +production: + stage: deploy + script: make deploy-to-prod + environment: + name: production ``` -## Defining environments +See the [yaml definition](yaml/README.md#environment) of environments. -You can create and delete environments manually in the web interface, but we -recommend that you define your environments in `.gitlab-ci.yml` first, which -will automatically create environments for you after the first deploy. +### View the environment status -The `environment` is just a hint for GitLab that this job actually deploys to -this environment. Each time the job succeeds, a deployment is recorded, -remembering the git SHA and environment. +GitLab keeps track of your deployments, so you always know what is currently +being deployed on your servers. You can find the environment list under +**Pipelines > Environments** for your project. You'll see the git SHA and date +of the last deployment to each environment defined. + +![Environments](img/environments_view.png) + +>**Note:** +Only deploys that happen after your `.gitlab-ci.yml` is properly configured will +show up in the "Environment" and "Last deployment" lists. + +## Manually deploying to environments + + +## 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`. + +GitLab Runner exposes various [environment variables][variables] when a job runs, +and as such you can use them -Add something like this to your `.gitlab-ci.yml`: ``` -production: +review: stage: deploy - script: dpl... - environment: production + script: + - rsync -av --delete public /srv/nginx/pages/$CI_BUILD_REF_NAME + environment: + name: review/$CI_BUILD_REF_NAME + url: https://$CI_BUILD_REF_NAME.example.com ``` -See full [documentation](yaml/README.md#environment). +### Closing an environment -## Seeing environment status +``` +review: + stage: deploy + script: + - rsync -av --delete public /srv/nginx/pages/$CI_BUILD_REF_NAME + environment: + name: review/$CI_BUILD_REF_NAME + url: http://$CI_BUILD_REF_NAME.$APPS_DOMAIN + on_stop: stop_review + +stop_review: + script: rm -rf /srv/nginx/pages/$CI_BUILD_REF_NAME + when: manual + environment: + name: review/$CI_BUILD_REF_NAME + action: stop +``` -You can find the environment list under **Pipelines > Environments** for your -project. You'll see the git SHA and date of the last deployment to each -environment defined. +## The relationship between deployments and environments ->**Note:** -Only deploys that happen after your `.gitlab-ci.yml` is properly configured will -show up in the environments and deployments lists. +Deployments are created when [jobs] 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. -## Seeing deployment history +### View the deployment history Clicking on an environment will show the history of deployments. +![Deployments](img/deployments_view.png) + >**Note:** Only deploys that happen after your `.gitlab-ci.yml` is properly configured will show up in the environments and deployments lists. +### Checkout deployments locally + +Since 8.13, a reference in the git repository is saved for each deployment. So +knowing what the state is of your current environments is only a `git fetch` +away. + +In your git config, append the `[remote ""]` block with an extra +fetch line: + +``` +fetch = +refs/environments/*:refs/remotes/origin/environments/* +``` + [Pipelines]: pipelines.md [jobs]: yaml/README.md#jobs +[yaml]: yaml/README.md [environments]: #environments [deployments]: #deployments +[permissions]: ../user/permissions.md +[variables]: variables/README.md diff --git a/doc/ci/img/deployments_view.png b/doc/ci/img/deployments_view.png new file mode 100644 index 00000000000..250e051bf42 Binary files /dev/null and b/doc/ci/img/deployments_view.png differ diff --git a/doc/ci/img/environments_view.png b/doc/ci/img/environments_view.png new file mode 100644 index 00000000000..131a9718cc4 Binary files /dev/null and b/doc/ci/img/environments_view.png differ diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 5c0e1c44e3f..5c7d300e3d9 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -573,7 +573,8 @@ In its simplest form, the `environment` keyword can be defined like: deploy to production: stage: deploy script: git push production HEAD:master - environment: production + environment: + name: production ``` In the above example, the `deploy to production` job will be marked as doing a @@ -673,6 +674,61 @@ The `stop_review_app` job is **required** to have the following keywords defined - `environment:name` - `environment:action` +#### environment:name + +#### environment:url + +Optional. + +#### environment:on_stop + +> [Introduced][ce-6669] in GitLab 8.13. + +Closing environments can be achieved with the `on_stop` keyword defined under +`environment`. It declares a different job that has to be run in order to close +the environment. + +This job is required to have the following keywords defined: + +- `when` - [reference](#when) +- `environment:name` +- `environment:action` - reference below + +See below for an example. + +#### environment:action + +> [Introduced][ce-6669] in GitLab 8.13. + +The `action` keyword is to be used in conjunction with `on_stop` and is defined +in the job that depends on the one that was called from. + +Take for instance: + +```yaml +review: + stage: deploy + script: make deploy-app + environment: + name: review + on_stop: stop_review + +stop_review: + stage: deploy + script: make delete-app + when: manual + environment: + name: review + action: stop +``` + +In the above example we set up the `review` job to deploy to the `review` +environment, and we also defined a new `stop_review` job under `on_stop`. +Once the `review` job is successfully finished, it will trigger the `stop_review` +job based on what is defined under `when`. In this case we set it up to `manual` +so it will need a [manual action](#manual-actions) via GitLab's web interface +in order to run. + #### dynamic environments > [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. @@ -681,7 +737,9 @@ The `stop_review_app` job is **required** to have the following keywords defined These parameters can use any of the defined [CI variables](#variables) (including predefined, secure variables and `.gitlab-ci.yml` variables). -For example: +--- + +**Example configurations** ``` deploy as review app: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index d6216a8dd50..a33183fa01c 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -32,6 +32,8 @@ The following table depicts the various user permission levels in a project. | See a commit status | | ✓ | ✓ | ✓ | ✓ | | See a container registry | | ✓ | ✓ | ✓ | ✓ | | See environments | | ✓ | ✓ | ✓ | ✓ | +| Create new environments | | | ✓ | ✓ | ✓ | +| Delete environments | | | | ✓ | ✓ | | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | | Create new merge request | | | ✓ | ✓ | ✓ | @@ -45,7 +47,6 @@ The following table depicts the various user permission levels in a project. | Create or update commit status | | | ✓ | ✓ | ✓ | | Update a container registry | | | ✓ | ✓ | ✓ | | Remove a container registry image | | | ✓ | ✓ | ✓ | -| Create new environments | | | ✓ | ✓ | ✓ | | Create new milestones | | | | ✓ | ✓ | | Add new team members | | | | ✓ | ✓ | | Push to protected branches | | | | ✓ | ✓ | @@ -58,7 +59,6 @@ The following table depicts the various user permission levels in a project. | Manage runners | | | | ✓ | ✓ | | Manage build triggers | | | | ✓ | ✓ | | Manage variables | | | | ✓ | ✓ | -| Delete environments | | | | ✓ | ✓ | | Switch visibility level | | | | | ✓ | | Transfer project to another namespace | | | | | ✓ | | Remove project | | | | | ✓ | -- cgit v1.2.1 From 8666fd7613e0e4c3eaaf3e730f0cb0ac75aff245 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Fri, 4 Nov 2016 11:20:44 +0100 Subject: Begin writing Overview section --- doc/ci/environments.md | 57 +++++++++++++++++++++++----------------------- doc/ci/yaml/README.md | 62 ++------------------------------------------------ 2 files changed, 30 insertions(+), 89 deletions(-) diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 9d65621fbbb..60541c44016 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -3,20 +3,38 @@ >**Note:** Introduced in GitLab 8.9. -During the development of a software there can be many stages until it's ready -for public consumption. You sure want to first see your code 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. - -With environments you can control the Continuous Deployment of your software all +During the development of a 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. + +In case you use GitLab CI to not only test or build your project, but also +deploy it in your infrastructure, GitLab provides a way to track your deployments +so you always know what is currently being deployed on your servers. 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]. +[`.gitlab-ci.yml`][yaml]. GitLab provides a full history of your deployments per +every environment. + +## Overview + +Deployments are created when [jobs] 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. + +Environments are like tags for your CI jobs, describing where code gets deployed. +CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. +You can think of names such as testing, staging or production. -In the following sections, we'll see how that works. +Defining environments in a project's `.gitlab-ci.yml` lets developers track +[deployments] to these environments. -## An environments example +The environments page can only be viewed by Reporters and above. For more +information on the permissions, see the [permissions documentation][permissions]. -Let's assume that you have +Let's assume that you have: 1. Define the environments in `.gitlab-ci.yml` 1. Push the repository to GitLab @@ -41,18 +59,6 @@ View commit SHA that triggered the deployment View branch the deployment was based on View time ago the deployment was performed -Environments are like tags for your CI jobs, describing where code gets deployed. - -You can think of names such as testing, staging or production. - -CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. - -Defining environments in a project's `.gitlab-ci.yml` lets developers track -[deployments] to these environments. - -The environments page can only be viewed by Reporters and above. For more -information on the permissions, see the [permissions documentation][permissions]. - ### Defining environments While you can create and delete environments manually in the web interface, we @@ -129,13 +135,6 @@ stop_review: action: stop ``` -## The relationship between deployments and environments - -Deployments are created when [jobs] 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. - ### View the deployment history Clicking on an environment will show the history of deployments. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 5c7d300e3d9..5c0e1c44e3f 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -573,8 +573,7 @@ In its simplest form, the `environment` keyword can be defined like: deploy to production: stage: deploy script: git push production HEAD:master - environment: - name: production + environment: production ``` In the above example, the `deploy to production` job will be marked as doing a @@ -674,61 +673,6 @@ The `stop_review_app` job is **required** to have the following keywords defined - `environment:name` - `environment:action` -#### environment:name - -#### environment:url - -Optional. - -#### environment:on_stop - -> [Introduced][ce-6669] in GitLab 8.13. - -Closing environments can be achieved with the `on_stop` keyword defined under -`environment`. It declares a different job that has to be run in order to close -the environment. - -This job is required to have the following keywords defined: - -- `when` - [reference](#when) -- `environment:name` -- `environment:action` - reference below - -See below for an example. - -#### environment:action - -> [Introduced][ce-6669] in GitLab 8.13. - -The `action` keyword is to be used in conjunction with `on_stop` and is defined -in the job that depends on the one that was called from. - -Take for instance: - -```yaml -review: - stage: deploy - script: make deploy-app - environment: - name: review - on_stop: stop_review - -stop_review: - stage: deploy - script: make delete-app - when: manual - environment: - name: review - action: stop -``` - -In the above example we set up the `review` job to deploy to the `review` -environment, and we also defined a new `stop_review` job under `on_stop`. -Once the `review` job is successfully finished, it will trigger the `stop_review` -job based on what is defined under `when`. In this case we set it up to `manual` -so it will need a [manual action](#manual-actions) via GitLab's web interface -in order to run. - #### dynamic environments > [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6. @@ -737,9 +681,7 @@ in order to run. These parameters can use any of the defined [CI variables](#variables) (including predefined, secure variables and `.gitlab-ci.yml` variables). ---- - -**Example configurations** +For example: ``` deploy as review app: -- cgit v1.2.1 From dd3c2714689421ad782bbbb3f9c09e81b8b20e71 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Mon, 7 Nov 2016 20:57:18 +0100 Subject: Move paragraph to overview --- doc/ci/environments.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 60541c44016..0c1557eeaef 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -11,20 +11,21 @@ process as well. In case you use GitLab CI to not only test or build your project, but also deploy it in your infrastructure, GitLab provides a way to track your deployments -so you always know what is currently being deployed on your servers. 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]. GitLab provides a full history of your deployments per -every environment. +so you always know what is currently being deployed on your servers. ## Overview +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] 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. -Environments are like tags for your CI jobs, describing where code gets deployed. CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. You can think of names such as testing, staging or production. -- cgit v1.2.1 From 21f1bee2c6ebb4ab307fab19e6560245a9fdb0d7 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 16 Nov 2016 17:13:08 +0100 Subject: Add section on defining environments [ci skip] --- doc/ci/environments.md | 166 ++++++++++++++++++-------- doc/ci/img/environments_available_staging.png | Bin 0 -> 27398 bytes 2 files changed, 114 insertions(+), 52 deletions(-) create mode 100644 doc/ci/img/environments_available_staging.png diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 0c1557eeaef..b3d4ec40830 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -3,20 +3,21 @@ >**Note:** Introduced in GitLab 8.9. -During the development of a software, there can be many stages until it's ready +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. -In case you use GitLab CI to not only test or build your project, but also -deploy it in your infrastructure, GitLab provides a way to track your deployments -so you always know what is currently being deployed on your servers. +GitLab CI 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 -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 +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. @@ -26,63 +27,97 @@ 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. -CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. -You can think of names such as testing, staging or production. +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: -Defining environments in a project's `.gitlab-ci.yml` lets developers track -[deployments] to these 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 -The environments page can only be viewed by Reporters and above. For more -information on the permissions, see the [permissions documentation][permissions]. +Let's see how it all ties together. -Let's assume that you have: +## Defining environments -1. Define the environments in `.gitlab-ci.yml` -1. Push the repository to GitLab -1. Runner picks up the job -1. The job finishes successfully -1. The environments get created if they don't already exist -1. A deployment is recorded remembering the environment name and the Git SHA of - the last commit of the pipeline +Let's consider the following `.gitlab-ci.yml` example: -Further runs of the CI will +```yaml +stages: + - test + - build + - deploy -Actions +test: + stage: test + script: echo "Running tests" -View environments -View deployments - Rollback deployments - Run deployments -View link to environment URL -View last commit message of deployment -View person who performed the deployment -View commit SHA that triggered the deployment -View branch the deployment was based on -View time ago the deployment was performed +build: + stage: build + script: echo "Building the app" -### Defining environments +deploy_staging: + stage: deploy + script: + - echo "Deploy to staging server" + environment: + name: staging + url: https://staging.example.com + only: + - master +``` -While you can create and delete 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. +We have defined 3 [stages](yaml/README.md#stages): -The `environment` keyword is just a hint for GitLab that this job actually -deploys to this environment. Each time the job succeeds, a deployment is -recorded, remembering the Git SHA and environment name. +- test +- build +- deploy -Add something like this to your `.gitlab-ci.yml`: +The jobs assigned to these stages will run in this order. If a job fails, then +the builds 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. -``` -production: - stage: deploy - script: make deploy-to-prod - environment: - name: production -``` +With the above `.gitlab-ci.yml` we have achieved that: -See the [yaml definition](yaml/README.md#environment) of environments. +- All branches will run the `test` and `build` jobs. +- The `deploy_staging` job will [only](yaml/README.md#only) run on the `master` + branch which means all merge requests +- 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`. -### View the environment status +The `environment` keyword is just a hint for GitLab that this job actually +deploys to this environment. Each time the job succeeds, a deployment is +recorded, remembering the Git SHA and environment name. Here's how the +Environments page looks so far. + +![Staging environment view](img/environments_available_staging.png) + +TODO: describe what the above page means + +>**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]. + +As we've pointed in the Overview section, environments are like tags for your +CI jobs, describing where code gets deployed. Here's what happened behind the +scenes: + +1. The jobs and environments were defined in `.gitlab-ci.yml` +1. Changes were pushed to the repository in GitLab +1. The Runner(s) picked up the jobs +1. The jobs finished successfully +1. The environments got created if they didn't already exist +1. A deployment was recorded remembering the environment name and the Git SHA of + the last commit of the pipeline + +## View the environment status GitLab keeps track of your deployments, so you always know what is currently being deployed on your servers. You can find the environment list under @@ -97,6 +132,9 @@ show up in the "Environment" and "Last deployment" lists. ## Manually deploying to environments +CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. +You can think of names such as testing, staging or production. + ## Dynamic environments @@ -116,7 +154,7 @@ review: url: https://$CI_BUILD_REF_NAME.example.com ``` -### Closing an environment +## Closing an environment ``` review: @@ -136,7 +174,7 @@ stop_review: action: stop ``` -### View the deployment history +## View the deployment history Clicking on an environment will show the history of deployments. @@ -146,7 +184,7 @@ Clicking on an environment will show the history of deployments. Only deploys that happen after your `.gitlab-ci.yml` is properly configured will show up in the environments and deployments lists. -### Checkout deployments locally +## Checkout deployments locally Since 8.13, a reference in the git repository is saved for each deployment. So knowing what the state is of your current environments is only a `git fetch` @@ -159,6 +197,30 @@ fetch line: fetch = +refs/environments/*:refs/remotes/origin/environments/* ``` +## Further reading + +Below are some links you may find interesting: + +- [The `.gitlab-ci.yml` definition of environments](yaml/README.md#environment) +- [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) +- [Review Apps](review_apps.md) Expand dynamic environments to deploy your code for every branch + + +## WIP + +Actions + +View environments +View deployments + Rollback deployments + Run deployments +View link to environment URL +View last commit message of deployment +View person who performed the deployment +View commit SHA that triggered the deployment +View branch the deployment was based on +View time ago the deployment was performed + [Pipelines]: pipelines.md [jobs]: yaml/README.md#jobs [yaml]: yaml/README.md diff --git a/doc/ci/img/environments_available_staging.png b/doc/ci/img/environments_available_staging.png new file mode 100644 index 00000000000..784c4fd944c Binary files /dev/null and b/doc/ci/img/environments_available_staging.png differ -- cgit v1.2.1 From 5cac52d8e05492d78869974c4ee9a928da7c6983 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Wed, 16 Nov 2016 17:20:07 +0100 Subject: Change deployments view image [ci skip] --- doc/ci/img/deployments_view.png | Bin 179909 -> 57598 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/doc/ci/img/deployments_view.png b/doc/ci/img/deployments_view.png index 250e051bf42..ca6097cbea4 100644 Binary files a/doc/ci/img/deployments_view.png and b/doc/ci/img/deployments_view.png differ -- cgit v1.2.1 From 3a6e38db5316a73809c3303de2aa8a0ece866fcc Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 17 Nov 2016 00:04:28 +0100 Subject: Finish most of environments [ci skip] --- doc/ci/environments.md | 184 +++++++++++++++------ doc/ci/img/environments_manual_action_builds.png | Bin 0 -> 27170 bytes .../img/environments_manual_action_deployments.png | Bin 0 -> 34504 bytes .../environments_manual_action_environments.png | Bin 0 -> 40297 bytes .../img/environments_manual_action_pipelines.png | Bin 0 -> 42212 bytes .../environments_manual_action_single_pipeline.png | Bin 0 -> 42233 bytes 6 files changed, 132 insertions(+), 52 deletions(-) create mode 100644 doc/ci/img/environments_manual_action_builds.png create mode 100644 doc/ci/img/environments_manual_action_deployments.png create mode 100644 doc/ci/img/environments_manual_action_environments.png create mode 100644 doc/ci/img/environments_manual_action_pipelines.png create mode 100644 doc/ci/img/environments_manual_action_single_pipeline.png diff --git a/doc/ci/environments.md b/doc/ci/environments.md index b3d4ec40830..a96e975bb92 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -59,10 +59,10 @@ build: deploy_staging: stage: deploy script: - - echo "Deploy to staging server" + - echo "Deploy to staging server" environment: - name: staging - url: https://staging.example.com + name: staging + url: https://staging.example.com only: - master ``` @@ -80,23 +80,45 @@ 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. -With the above `.gitlab-ci.yml` we have achieved that: +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 +the Git SHA and environment name. + +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 [only](yaml/README.md#only) run on the `master` - branch which means all merge requests +- The `deploy_staging` job will run [only](yaml/README.md#only) 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`. -The `environment` keyword is just a hint for GitLab that this job actually -deploys to this environment. Each time the job succeeds, a deployment is -recorded, remembering the Git SHA and environment name. Here's how the -Environments page looks so far. +Let's now see how that information is exposed within GitLab. + +## Viewing the current status of an environment + +The environment list under your project's **Pipelines ➔ Environments**, is +where you can find information of the last deployment status of an environment. + +Here's how the Environments page looks so far. ![Staging environment view](img/environments_available_staging.png) -TODO: describe what the above page means +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 build 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 @@ -104,37 +126,105 @@ TODO: describe what the above page means 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. -As we've pointed in the Overview section, environments are like tags for your -CI jobs, describing where code gets deployed. Here's what happened behind the -scenes: +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. -1. The jobs and environments were defined in `.gitlab-ci.yml` -1. Changes were pushed to the repository in GitLab -1. The Runner(s) picked up the jobs -1. The jobs finished successfully -1. The environments got created if they didn't already exist -1. A deployment was recorded remembering the environment name and the Git SHA of - the last commit of the pipeline - -## View the environment status +## 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. You can find the environment list under -**Pipelines > Environments** for your project. You'll see the git SHA and date -of the last deployment to each environment defined. +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. + +![Deployments](img/deployments_view.png) -![Environments](img/environments_view.png) +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 +(**Pipelines ➔ Environments ➔ `environment name`**) you can relaunch the +job with the commit associated with it. >**Note:** -Only deploys that happen after your `.gitlab-ci.yml` is properly configured will -show up in the "Environment" and "Last deployment" lists. +Bare 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 -CI/CD [Pipelines] usually have one or more [jobs] that deploy to an environment. -You can think of names such as testing, staging or production. +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: +```yaml +stages: + - test + - build + - deploy + +test: + stage: test + script: echo "Running tests" + +build: + stage: build + script: echo "Building the app" + +deploy_staging: + stage: deploy + script: + - echo "Deploy to staging server" + environment: + name: staging + url: https://staging.example.com + only: + - master + +deploy_prod: + stage: deploy + script: + - echo "Deploy to production server" + environment: + name: production + url: https://example.com + when: manual + only: + - master +``` + +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, build, environment, and deployment views. + +| Pipelines | Single pipeline | Environments | Deployments | Builds | +| --------- | ----------------| ------------ | ----------- | -------| +| ![Pipelines manual action](img/environments_manual_action_pipelines.png) | ![Pipelines manual action](img/environments_manual_action_single_pipeline.png) | ![Environments manual action](img/environments_manual_action_environments.png) | ![Deployments manual action](img/environments_manual_action_deployments.png) | ![Builds manual action](img/environments_manual_action_builds.png) | + +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 +environment named `production`. + +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. ## Dynamic environments @@ -174,16 +264,6 @@ stop_review: action: stop ``` -## View the deployment history - -Clicking on an environment will show the history of deployments. - -![Deployments](img/deployments_view.png) - ->**Note:** -Only deploys that happen after your `.gitlab-ci.yml` is properly configured will -show up in the environments and deployments lists. - ## Checkout deployments locally Since 8.13, a reference in the git repository is saved for each deployment. So @@ -206,20 +286,20 @@ Below are some links you may find interesting: - [Review Apps](review_apps.md) Expand dynamic environments to deploy your code for every branch -## WIP +## TODO Actions -View environments -View deployments - Rollback deployments - Run deployments -View link to environment URL -View last commit message of deployment -View person who performed the deployment -View commit SHA that triggered the deployment -View branch the deployment was based on -View time ago the deployment was performed +- View environments + +- View deployments + + - Rollback deployments + + - Run deployments + +- View link to environment URL +- View last commit message of deployment + +- View person who performed the deployment + +- View commit SHA that triggered the deployment + +- View branch the deployment was based on + +- View time ago the deployment was performed + [Pipelines]: pipelines.md [jobs]: yaml/README.md#jobs diff --git a/doc/ci/img/environments_manual_action_builds.png b/doc/ci/img/environments_manual_action_builds.png new file mode 100644 index 00000000000..d4bb7ccdbae Binary files /dev/null and b/doc/ci/img/environments_manual_action_builds.png differ diff --git a/doc/ci/img/environments_manual_action_deployments.png b/doc/ci/img/environments_manual_action_deployments.png new file mode 100644 index 00000000000..c2477381c80 Binary files /dev/null and b/doc/ci/img/environments_manual_action_deployments.png differ diff --git a/doc/ci/img/environments_manual_action_environments.png b/doc/ci/img/environments_manual_action_environments.png new file mode 100644 index 00000000000..56601c0db2d Binary files /dev/null and b/doc/ci/img/environments_manual_action_environments.png differ diff --git a/doc/ci/img/environments_manual_action_pipelines.png b/doc/ci/img/environments_manual_action_pipelines.png new file mode 100644 index 00000000000..eb6e87cd956 Binary files /dev/null and b/doc/ci/img/environments_manual_action_pipelines.png differ diff --git a/doc/ci/img/environments_manual_action_single_pipeline.png b/doc/ci/img/environments_manual_action_single_pipeline.png new file mode 100644 index 00000000000..9713ad212e2 Binary files /dev/null and b/doc/ci/img/environments_manual_action_single_pipeline.png differ -- cgit v1.2.1 From ff97de61df3ebbeea31e5fef833e8a477c13ab3c Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 17 Nov 2016 08:54:51 +0100 Subject: Move name rules under environment:name in yaml readme --- doc/ci/yaml/README.md | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 5c0e1c44e3f..bc9c0897f5a 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -552,28 +552,14 @@ An example usage of manual actions is deployment to production. If `environment` is specified and no environment under that name exists, a new one will be created automatically. -The `environment` name can contain: - -- letters -- digits -- spaces -- `-` -- `_` -- `/` -- `$` -- `{` -- `}` - -Common names are `qa`, `staging`, and `production`, but you can use whatever -name works with your workflow. - In its simplest form, the `environment` keyword can be defined like: ``` deploy to production: stage: deploy script: git push production HEAD:master - environment: production + environment: + name: production ``` In the above example, the `deploy to production` job will be marked as doing a @@ -588,6 +574,21 @@ Before GitLab 8.11, the name of an environment could be defined as a string like `environment: production`. The recommended way now is to define it under the `name` keyword. +The `environment` name can contain: + +- letters +- digits +- spaces +- `-` +- `_` +- `/` +- `$` +- `{` +- `}` + +Common names are `qa`, `staging`, and `production`, but you can use whatever +name works with your workflow. + Instead of defining the name of the environment right after the `environment` keyword, it is also possible to define it as a separate value. For that, use the `name` keyword under `environment`: -- cgit v1.2.1 From 54fc574ebad57fddeaede8edeae04d53031d7712 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 17 Nov 2016 10:36:58 +0100 Subject: Finish dynamic environments and URLs sections [ci skip] --- doc/ci/environments.md | 160 ++++++++++++++++++++++- doc/ci/img/environments_link_url.png | Bin 0 -> 33561 bytes doc/ci/img/environments_link_url_deployments.png | Bin 0 -> 19652 bytes doc/ci/img/environments_link_url_mr.png | Bin 0 -> 47347 bytes doc/ci/img/environments_mr_review_app.png | Bin 0 -> 39780 bytes 5 files changed, 156 insertions(+), 4 deletions(-) create mode 100644 doc/ci/img/environments_link_url.png create mode 100644 doc/ci/img/environments_link_url_deployments.png create mode 100644 doc/ci/img/environments_link_url_mr.png create mode 100644 doc/ci/img/environments_mr_review_app.png diff --git a/doc/ci/environments.md b/doc/ci/environments.md index a96e975bb92..428e8a0cf25 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -221,6 +221,11 @@ 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 environment named `production`. +>**Note:** +Remember that if your environment's name is `production` (all lowercase), then +it will get recorded in [Cycle Analytics](../user/project/cycle_analytics.md). +Double the benefit! + 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 @@ -229,21 +234,162 @@ will help us achieve that. ## 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`. +declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments is +the base of [Review apps](review_apps.md). GitLab Runner exposes various [environment variables][variables] when a job runs, -and as such you can use them +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`: +```yaml +deploy_review: + stage: deploy + script: + - echo "Deploy a review app" + environment: + name: review/$CI_BUILD_REF_NAME + url: https://$CI_BUILD_REF_NAME.example.com + only: + - branches + except: + - master ``` -review: + +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_BUILD_REF_NAME`. Now that's an interesting +one. Since the [environment name][env-name] can contain also 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_BUILD_REF_NAME` +which takes the value of the branch name. We also use the same +`$CI_BUILD_REF_NAME` value in the `environment:url` so that the environment +can get a specific and distinct URL for each branch. Again, the way you set up +the webserver to serve these requests is based on your setup. + +Last but not least, we tell the job to run [`only`][only] on branches +[`except`][only] master. + +>**Note:** +You are not bound to use only slashes in the dynamic environments' names (`/`), +but as we will see later, this will enable the "grouping similar environments" +feature. + +The whole `.gitlab-ci.yml` looks like this so far: + +```yaml +stages: + - test + - build + - deploy + +test: + stage: test + script: echo "Running tests" + +build: + stage: build + script: echo "Building the app" + +deploy_review: stage: deploy script: - - rsync -av --delete public /srv/nginx/pages/$CI_BUILD_REF_NAME + - echo "Deploy a review app" environment: name: review/$CI_BUILD_REF_NAME url: https://$CI_BUILD_REF_NAME.example.com + only: + - branches + except: + - master + +deploy_staging: + stage: deploy + script: + - echo "Deploy to staging server" + environment: + name: staging + url: https://staging.example.com + only: + - master + +deploy_prod: + stage: deploy + script: + - echo "Deploy to production server" + environment: + name: production + url: https://example.com + when: manual + only: + - master ``` +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_BUILD_REF_NAME/public`: + +```yaml +review_app: + stage: deploy + script: + - rsync -av --delete public /srv/nginx/$CI_BUILD_REF_NAME + environment: + name: review/$CI_BUILD_REF_NAME + url: https://$CI_BUILD_REF_NAME.example.com +``` + +It is assumed that the user has already setup NGINX and GitLab Runner in the +server this job will run on. + +--- + +The development workflow would now be: + +- Developer creates a branch locally +- Developer makes changes, commits and pushes the branch to GitLab +- Developer creates a merge request + +Behind the scenes: + +- 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 build begins and successfully also passes + - Lastly, the app is deployed to an environment with a name specific to the + branch + +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. + +## Making use of the environment URL + +The environment URL 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 | +| -------------------- | ------------ | ----------- | +| ![Environment URL in merge request](img/environments_mr_review_app.png) | ![Environment URL in environments](img/environments_link_url.png) | ![Environment URL in deployments](img/environments_link_url_deployments.png) | + +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. + +![Environment URLs in merge request](img/environments_link_url_mr.png) + +--- + +We now have a full development cycle, where our 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. What we just described +is a single workflow, but imagine tens of developers working on a project +at the same time. They each push to their branches, and dynamic environments are +created all the time. In that case, we probably need to do some clean up. Read +next how environments can be closed. + ## Closing an environment ``` @@ -264,6 +410,10 @@ stop_review: action: stop ``` +## Grouping similar environments + +folders in environments page + ## Checkout deployments locally Since 8.13, a reference in the git repository is saved for each deployment. So @@ -308,3 +458,5 @@ Actions [deployments]: #deployments [permissions]: ../user/permissions.md [variables]: variables/README.md +[env-name]: yaml/README.md#environment-name +[only]: yaml/README.md#only-and-except diff --git a/doc/ci/img/environments_link_url.png b/doc/ci/img/environments_link_url.png new file mode 100644 index 00000000000..224c21adfb5 Binary files /dev/null and b/doc/ci/img/environments_link_url.png differ diff --git a/doc/ci/img/environments_link_url_deployments.png b/doc/ci/img/environments_link_url_deployments.png new file mode 100644 index 00000000000..9419668a9bd Binary files /dev/null and b/doc/ci/img/environments_link_url_deployments.png differ diff --git a/doc/ci/img/environments_link_url_mr.png b/doc/ci/img/environments_link_url_mr.png new file mode 100644 index 00000000000..3276dfb6096 Binary files /dev/null and b/doc/ci/img/environments_link_url_mr.png differ diff --git a/doc/ci/img/environments_mr_review_app.png b/doc/ci/img/environments_mr_review_app.png new file mode 100644 index 00000000000..a2ae25d62fa Binary files /dev/null and b/doc/ci/img/environments_mr_review_app.png differ -- cgit v1.2.1 From 556aaebc22b58d1e496512323173ea1ca28370d1 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 17 Nov 2016 11:58:57 +0100 Subject: Finish "Stopping envs" and "Grouping similar envs" sections [ci skip] --- doc/ci/environments.md | 83 +++++++++++++++++++---------- doc/ci/img/environments_dynamic_groups.png | Bin 0 -> 134164 bytes 2 files changed, 56 insertions(+), 27 deletions(-) create mode 100644 doc/ci/img/environments_dynamic_groups.png diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 428e8a0cf25..861a639b3fc 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -273,9 +273,9 @@ Last but not least, we tell the job to run [`only`][only] on branches [`except`][only] master. >**Note:** -You are not bound to use only slashes in the dynamic environments' names (`/`), -but as we will see later, this will enable the "grouping similar environments" -feature. +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. The whole `.gitlab-ci.yml` looks like this so far: @@ -388,31 +388,74 @@ and finally manually deployed to the production server. What we just described is a single workflow, but imagine tens of developers working on a project at the same time. They each push to their branches, and dynamic environments are created all the time. In that case, we probably need to do some clean up. Read -next how environments can be closed. +next how environments can be stopped. -## Closing an environment +## Stopping an environment -``` -review: +By stopping an environment, you are effectively terminating its recording of the +deployments that happen in it. + +>**Note:** +Starting with GitLab 8.14, dynamic environments will be stopped automatically +when their associated branch is removed. + +There is a special case where environments can be manually closed. 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. + +Consider the following example where the `deploy_review` calls the `stop_review` +to clean up and stop the environment: + +```yaml +deploy_review: stage: deploy script: - - rsync -av --delete public /srv/nginx/pages/$CI_BUILD_REF_NAME + - echo "Deploy a review app" environment: name: review/$CI_BUILD_REF_NAME - url: http://$CI_BUILD_REF_NAME.$APPS_DOMAIN + url: https://$CI_BUILD_REF_NAME.example.com on_stop: stop_review + only: + - branches + except: + - master stop_review: - script: rm -rf /srv/nginx/pages/$CI_BUILD_REF_NAME + script: + - echo "Remove review app" when: manual environment: name: review/$CI_BUILD_REF_NAME action: stop ``` +You can read more in the [`.gitlab-ci.yml` reference][onstop]. + ## Grouping similar environments -folders in environments page +> [Introduced][ce-7015] in GitLab 8.14. + +As we've seen in the [dynamic environments](#dynamic-environments), you can + +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_BUILD_REF_NAME` +where `$CI_BUILD_REF_NAME` is the branch name: + +```yaml +deploy_review: + stage: deploy + script: + - echo "Deploy a review app" + environment: + name: review/$CI_BUILD_REF_NAME +``` + +In that case, if you visit the Environments page, and provided the branches +exist, you should see something like: + +![Environment groups](img/environments_dynamic_groups.png) ## Checkout deployments locally @@ -435,22 +478,6 @@ Below are some links you may find interesting: - [A blog post on Deployments & Environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) - [Review Apps](review_apps.md) Expand dynamic environments to deploy your code for every branch - -## TODO - -Actions - -- View environments + -- View deployments + - - Rollback deployments + - - Run deployments + -- View link to environment URL -- View last commit message of deployment + -- View person who performed the deployment + -- View commit SHA that triggered the deployment + -- View branch the deployment was based on + -- View time ago the deployment was performed + - [Pipelines]: pipelines.md [jobs]: yaml/README.md#jobs [yaml]: yaml/README.md @@ -460,3 +487,5 @@ Actions [variables]: variables/README.md [env-name]: yaml/README.md#environment-name [only]: yaml/README.md#only-and-except +[onstop]: yaml/README.md#environment-on_stop +[ce-7015]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7015 diff --git a/doc/ci/img/environments_dynamic_groups.png b/doc/ci/img/environments_dynamic_groups.png new file mode 100644 index 00000000000..e89b66c502c Binary files /dev/null and b/doc/ci/img/environments_dynamic_groups.png differ -- cgit v1.2.1 From 9ea4a5bca589aa095dd3b633245b551b4c758d82 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 17 Nov 2016 12:15:06 +0100 Subject: Add note about auto-stopping of environments --- doc/ci/environments.md | 17 +++++++++++++---- doc/ci/yaml/README.md | 7 ++++++- 2 files changed, 19 insertions(+), 5 deletions(-) diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 861a639b3fc..cc65f0ad8ad 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -395,11 +395,12 @@ next how environments can be stopped. By stopping an environment, you are effectively terminating its recording of the deployments that happen in it. ->**Note:** -Starting with GitLab 8.14, dynamic environments will be stopped automatically -when their associated branch is removed. +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`. -There is a special case where environments can be manually closed. That can +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. @@ -429,6 +430,14 @@ stop_review: action: stop ``` +>**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 +stop action when the associated branch is deleted. + You can read more in the [`.gitlab-ci.yml` reference][onstop]. ## Grouping similar environments diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index bc9c0897f5a..1e096444903 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -627,7 +627,12 @@ deploy to production: #### environment:on_stop -> [Introduced][ce-6669] in GitLab 8.13. +> +**Notes:** +- [Introduced][ce-6669] in GitLab 8.13. +- Starting with GitLab 8.14, when you have an environment that has a stop action + defined, GitLab will automatically trigger a stop action when the associated + branch is deleted. Closing (stoping) environments can be achieved with the `on_stop` keyword defined under `environment`. It declares a different job that runs in order to close -- cgit v1.2.1 From e5aebccb640636cf0ea74b3569772b8a9156bb48 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Thu, 17 Nov 2016 12:16:13 +0100 Subject: Add stop environment permissions and remove delete [ci skip] --- doc/user/permissions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/user/permissions.md b/doc/user/permissions.md index a33183fa01c..cea78864df2 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -33,7 +33,7 @@ The following table depicts the various user permission levels in a project. | See a container registry | | ✓ | ✓ | ✓ | ✓ | | See environments | | ✓ | ✓ | ✓ | ✓ | | Create new environments | | | ✓ | ✓ | ✓ | -| Delete environments | | | | ✓ | ✓ | +| Stop environments | | | ✓ | ✓ | ✓ | | See a list of merge requests | | ✓ | ✓ | ✓ | ✓ | | Manage/Accept merge requests | | | ✓ | ✓ | ✓ | | Create new merge request | | | ✓ | ✓ | ✓ | -- cgit v1.2.1