Merge branch '25990-interactive-web-terminals-for-ci-cd-jobs-docs' into 'master'

Document Interactive web terminals for CI/CD jobs

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

5 files changed, 54 insertions, 0 deletions

diff --git a/doc/ci/README.md b/doc/ci/README.md
index 7666219acb0..d782d64e971 100644
--- a/doc/ci/README.md
+++ b/doc/ci/README.md
@@ -76,6 +76,8 @@ learn how to leverage its potential even more.
 - [Trigger pipelines on a schedule](../user/project/pipelines/schedules.md)
 - [Kubernetes clusters](../user/project/clusters/index.md) - Integrate one or
   more Kubernetes clusters to your project
+- [Interactive web terminal](interactive_web_terminal/index.md) - Open an interactive
+  web terminal to debug the running jobs
 
 ## GitLab CI/CD for Docker
 
diff --git a/doc/ci/interactive_web_terminal/img/finished_job_with_terminal_open.png b/doc/ci/interactive_web_terminal/img/finished_job_with_terminal_open.png
new file mode 100644
index 00000000000..199268a1486
--- /dev/null
+++ b/doc/ci/interactive_web_terminal/img/finished_job_with_terminal_open.png
diff --git a/doc/ci/interactive_web_terminal/img/interactive_web_terminal_page.png b/doc/ci/interactive_web_terminal/img/interactive_web_terminal_page.png
new file mode 100644
index 00000000000..b59c1b6bc43
--- /dev/null
+++ b/doc/ci/interactive_web_terminal/img/interactive_web_terminal_page.png
diff --git a/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png b/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png
new file mode 100644
index 00000000000..f92c6df07a1
--- /dev/null
+++ b/doc/ci/interactive_web_terminal/img/interactive_web_terminal_running_job.png
diff --git a/doc/ci/interactive_web_terminal/index.md b/doc/ci/interactive_web_terminal/index.md
new file mode 100644
index 00000000000..507aceb27fa
--- /dev/null
+++ b/doc/ci/interactive_web_terminal/index.md
@@ -0,0 +1,52 @@
+# Getting started with interactive web terminals
+
+> Introduced in GitLab 11.3.
+
+CAUTION: **Warning:**
+Interactive web terminals are in beta, so they might not work properly and
+lack features. For more information [follow issue #25990](https://gitlab.com/gitlab-org/gitlab-ce/issues/25990).
+
+Interactive web terminals give the user access to a terminal in GitLab for
+running one-of commands for their CI pipeline.
+
+NOTE: **Note:**
+This is not available for the shared Runners on GitLab.com.
+To make use of this feature, you need to provide your
+[own Runner](https://docs.gitlab.com/runner/install/) and properly
+[configure it](#configuration).
+
+## Configuration
+
+Two things need to be configured for the interactive web terminal to work:
+
+- The Runner needs to have [`[session_server]` configured
+  properly][session-server]
+- Web terminals need to be
+  [enabled](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support)
+
+## Debugging a running job
+
+NOTE: **Note:** Not all executors are
+[supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
+
+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
+running, on the right panel you can see a button `debug` that will open the terminal
+for the current job.
+
+![Example of job running with terminal
+available](img/interactive_web_terminal_running_job.png)
+
+When clicked, a new tab will open to the terminal page where you can access
+the terminal and type commands like a normal shell.
+
+![terminal of the job](img/interactive_web_terminal_page.png)
+
+If you have the terminal open and the job has finished with its tasks, the
+terminal will block the job from finishing for the duration configured in
+[`[session_server].terminal_max_retention_time`][session-server] until you
+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