WIP refactor environments

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 "<your-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 "<your-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

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:

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                        |         |            |             |          | ✓      |