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