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 (limited to 'doc/ci') 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.3