Document environments and deployments

2 files changed, 60 insertions, 0 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index ef72df97ce6..5a1cb5319c6 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -5,6 +5,7 @@
 - [Get started with GitLab CI](quick_start/README.md)
 - [CI examples for various languages](examples/README.md)
 - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md)
+- [Environments and deployments](environments.md)
 - [Learn how `.gitlab-ci.yml` works](yaml/README.md)
 - [Configure a Runner, the application that runs your builds](runners/README.md)
 - [Use Docker images with GitLab Runner](docker/using_docker_images.md)
diff --git a/doc/ci/environments.md b/doc/ci/environments.md
new file mode 100644
index 00000000000..ee4c4c6025c
--- /dev/null
+++ b/doc/ci/environments.md
@@ -0,0 +1,59 @@
+# Introduction to environments and deployments
+
+>**Note:**
+Introduced in GitLab 8.9.
+
+## Environments
+
+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
+
+Deployments are created when [jobs] deploy versions of code to [environments].
+
+## Defining environments
+
+>**Note:**
+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]: quick_start/README.md
+[jobs]: yaml/README.md#jobs
+[environments]: #environments
+[deployments]: #deployments