Add documentation for DOCKER_STRATEGYdocs/runner-3605-document-new-docker-strategy

2 files changed, 42 insertions, 6 deletions

diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md
index 1ddc1bf4d7e..341643e647f 100644
--- a/doc/ci/interactive_web_terminal/index.md
+++ b/doc/ci/interactive_web_terminal/index.md
@@ -25,11 +25,9 @@ Two things need to be configured for the interactive web terminal to work:
 NOTE: **Note:** Not all executors are
 [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
 
-NOTE: **Note:** The `docker` executor does not keep running
-after the build script is finished. At that point, the terminal will automatically
-disconnect and will not wait for the user to finish. Please follow [this
-issue](https://gitlab.com/gitlab-org/gitlab-runner/issues/3605) for updates on
-improving this behavior.
+NOTE: **Note:** For full support on `docker` executor please use the
+[DOCKER_STRATEGY: exec][docker-strategy] inside of `.gitlab-ci.yml` variables
+declaration.
 
 Sometimes, when a job is running, things don't go as you would expect, and it
 would be helpful if one can have a shell to aid debugging. When a job is
@@ -52,3 +50,4 @@ close the terminal window.
 ![finished job with terminal open](img/finished_job_with_terminal_open.png)
 
 [session-server]: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section
+[docker-strategy]: ../yaml/README.md#docker-strategy
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 4b2a6ccc7e4..d4740273784 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1836,6 +1836,42 @@ variables:
 
 You can set it globally or per-job in the [`variables`](#variables) section.
 
+### Docker Strategy
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/issues/3605) in GitLab 11.4.
+
+You can set the `DOCKER_STRATEGY` either globally or per-job in
+[`variables`](#variables) section. If left unspecified, the default is
+`attach` which is the same behavior pre 11.4.
+
+`DOCKER_STRATEGY` defines the behavior of how the runner handle the build
+containers.
+
+`attach` is the default option, and follow the same behavior that the runner
+has been using. A container is started with the build script as the main
+process and exists as soon as the script is done.
+
+```yaml
+variables:
+  DOCKER_STRATEGY: attach
+```
+
+`exec` is the new workflow the runner follows to handle the build container,
+which tries to mimic the same way our [kubernetes
+executor](https://docs.gitlab.com/runner/executors/kubernetes.html) work.
+Meaning the build container is started in [detached
+mode](https://docs.docker.com/engine/reference/run/#detached--d) that invokes
+a shell. This allows the container to keep running until stopped/killed as
+the end of the stage. The build script is then executed using the `exec`
+functionality. Doing so will allow the runner to access the container even
+after the build script has started, such as [interactive web
+terminals][debugging-running-job].
+
+```yaml
+variables:
+  DOCKER_STRATEGY: exec
+```
+
 ## Special YAML features
 
 It's possible to use special YAML features like anchors (`&`), aliases (`*`)
@@ -2032,4 +2068,5 @@ CI with various languages.
 [schedules]: ../../user/project/pipelines/schedules.md
 [variables-expressions]: ../variables/README.md#variables-expressions
 [ee]: https://about.gitlab.com/gitlab-ee/
-[gitlab-versions]: https://about.gitlab.com/products/
\ No newline at end of file
+[gitlab-versions]: https://about.gitlab.com/products/
+[debugging-running-job]: ../interactive_web_terminal/index.md#debugging-a-running-job