Finish most of environments

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