Merge branch 'docs-use-variables-deploy-policy-for-staging-and-production' into 'master'

Include documentation about STAGING_ENABLED variable for AutoDevops

See merge request gitlab-org/gitlab-ce!18675

2 files changed, 23 insertions, 0 deletions

diff --git a/changelogs/unreleased/docs-use-variables-deploy-policy-for-staging-and-production.yml b/changelogs/unreleased/docs-use-variables-deploy-policy-for-staging-and-production.yml
new file mode 100644
index 00000000000..aa23a89a175
--- /dev/null
+++ b/changelogs/unreleased/docs-use-variables-deploy-policy-for-staging-and-production.yml
@@ -0,0 +1,6 @@
+---
+title: Add documentation about how to use variables to define deploy policies for
+  staging/production environments
+merge_request: 18675
+author:
+type: other
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index 7c0cd2c40d2..882ddf4d2c5 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -495,6 +495,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac
 | `POSTGRES_PASSWORD`          | The PostgreSQL password; defaults to `testing-password`. Set it to use a custom password.                                                                                                                                     |
 | `POSTGRES_DB`                | The PostgreSQL database name; defaults to the value of [`$CI_ENVIRONMENT_SLUG`](../../ci/variables/README.md#predefined-variables-environment-variables). Set it to use a custom database name.                               |
 | `BUILDPACK_URL`              | The buildpack's full URL. It can point to either Git repositories or a tarball URL. For Git repositories, it is possible to point to a specific `ref`, for example `https://github.com/heroku/heroku-buildpack-ruby.git#v142` |
+| `STAGING_ENABLED`            | From GitLab 10.8, this variable can be used to define a [deploy policy for staging and production environments](#deploy-policy-for-staging-and-production-environments). |
 
 TIP: **Tip:**
 Set up the replica variables using a
@@ -561,6 +562,22 @@ service:
   internalPort: 5000
 ```
 
+#### Deploy policy for staging and production environments
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ci-yml/merge_requests/160)
+in GitLab 10.8.
+
+The normal behavior of Auto DevOps is to use Continuous Deployment, pushing
+automatically to the `production` environment every time a new pipeline is run
+on the default branch. However, there are cases where you might want to use a
+staging environment and deploy to production manually. For this scenario, the
+`STAGING_ENABLED` environment variable was introduced.
+
+If `STAGING_ENABLED` is defined in your project (e.g., set `STAGING_ENABLED` to
+`1` as a secret variable), then the application will be automatically deployed
+to a `staging` environment, and a  `production_manual` job will be created for
+you when you're ready to manually deploy to production.
+
 ## Currently supported languages
 
 NOTE: **Note:**