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,16 +3,148 @@ >**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 + +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. + +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. + +Add something like this to your `.gitlab-ci.yml`: + +``` +production: + stage: deploy + script: make deploy-to-prod + environment: + name: production +``` + +See the [yaml definition](yaml/README.md#environment) of environments. + +### 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 +**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 + +``` +review: + stage: deploy + 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 +``` + +### Closing an environment + +``` +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 +``` + +## 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. + +![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 @@ -27,45 +159,10 @@ fetch line: fetch = +refs/environments/*:refs/remotes/origin/environments/* ``` -## Defining 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. - -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. - -Add something like this to your `.gitlab-ci.yml`: -``` -production: - stage: deploy - script: dpl... - environment: production -``` - -See full [documentation](yaml/README.md#environment). - -## Seeing environment status - -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. - ->**Note:** -Only deploys that happen after your `.gitlab-ci.yml` is properly configured will -show up in the environments and deployments lists. - -## Seeing deployment history - -Clicking on an environment will show the history of deployments. - ->**Note:** -Only deploys that happen after your `.gitlab-ci.yml` is properly configured will -show up in the environments and deployments lists. - [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 | | | | | ✓ |