2019-05-30 02:23:46 -04:00
---
2020-05-29 14:08:26 -04:00
stage: Verify
group: Runner
2022-09-21 17:13:33 -04:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2019-05-30 02:23:46 -04:00
type: reference
---
2021-09-07 20:11:00 -04:00
# Interactive Web Terminals **(FREE)**
2018-07-19 10:49:32 -04:00
2020-05-20 23:08:00 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/50144) in GitLab 11.3.
2018-08-17 02:14:25 -04:00
2018-07-19 10:49:32 -04:00
Interactive web terminals give the user access to a terminal in GitLab for
2021-08-24 14:10:53 -04:00
running one-off commands for their CI pipeline. You can think of it like a method for
debugging with SSH, but done directly from the job page. Since this is giving the user
2019-07-12 04:15:38 -04:00
shell access to the environment where [GitLab Runner ](https://docs.gitlab.com/runner/ )
2018-12-31 12:44:15 -05:00
is deployed, some [security precautions ](../../administration/integration/terminal.md#security ) were
taken to protect the users.
2018-07-19 10:49:32 -04:00
2020-12-04 16:09:29 -05:00
NOTE:
2021-06-28 08:38:12 -04:00
[Shared runners on GitLab.com ](../runners/index.md ) do not
2022-08-23 20:12:25 -04:00
provide an interactive web terminal. Follow
2022-08-07 23:09:21 -04:00
[this issue ](https://gitlab.com/gitlab-org/gitlab/-/issues/24674 ) for progress on
2019-01-29 03:23:31 -05:00
adding support. For groups and projects hosted on GitLab.com, interactive web
terminals are available when using your own group or project runner.
2018-07-19 10:49:32 -04:00
## Configuration
Two things need to be configured for the interactive web terminal to work:
2022-08-23 20:12:25 -04:00
- The runner needs to have
2022-08-07 23:09:21 -04:00
[`[session_server]` configured properly](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section)
2018-09-28 07:33:45 -04:00
- If you are using a reverse proxy with your GitLab instance, web terminals need to be
2018-07-19 10:49:32 -04:00
[enabled ](../../administration/integration/terminal.md#enabling-and-disabling-terminal-support )
2022-01-18 13:11:20 -05:00
### Partial support for Helm chart
Interactive web terminals are partially supported in `gitlab-runner` Helm chart.
They are enabled when:
- The number of replica is one
- You use the `loadBalancer` service
Support for fixing these limitations is tracked in the following issues:
- [Support of more than one replica ](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/323 )
- [Support of more service types ](https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/324 )
2019-09-12 00:39:39 -04:00
2018-07-19 10:49:32 -04:00
## Debugging a running job
2020-12-04 16:09:29 -05:00
NOTE:
2020-07-16 02:09:33 -04:00
Not all executors are
2018-07-19 10:49:32 -04:00
[supported ](https://docs.gitlab.com/runner/executors/#compatibility-chart ).
2020-12-04 16:09:29 -05:00
NOTE:
2020-07-16 02:09:33 -04:00
The `docker` executor does not keep running
2020-11-23 16:09:19 -05:00
after the build script is finished. At that point, the terminal automatically
2022-08-23 20:12:25 -04:00
disconnects and does not wait for the user to finish. Please follow
2022-08-07 23:09:21 -04:00
[this issue ](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3605 ) for updates on
2018-09-24 08:45:39 -04:00
improving this behavior.
2018-07-19 10:49:32 -04:00
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
2020-11-23 16:09:19 -05:00
running, on the right panel you can see a button `debug` that opens the terminal
2018-07-19 10:49:32 -04:00
for the current job.
2022-08-07 23:09:21 -04:00
![Example of job running with terminal available ](img/interactive_web_terminal_running_job.png )
2018-07-19 10:49:32 -04:00
2020-11-23 16:09:19 -05:00
When clicked, a new tab opens to the terminal page where you can access
2018-08-16 08:10:25 -04:00
the terminal and type commands like a normal shell.
2018-07-19 10:49:32 -04:00
![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
2020-11-23 16:09:19 -05:00
terminal blocks the job from finishing for the duration configured in
2019-11-04 01:06:46 -05:00
[`[session_server].session_timeout`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) until you
2018-07-19 10:49:32 -04:00
close the terminal window.
![finished job with terminal open ](img/finished_job_with_terminal_open.png )
2019-05-05 11:06:37 -04:00
2020-06-18 11:08:45 -04:00
## Interactive Web Terminals for the Web IDE
2019-05-05 11:06:37 -04:00
2020-06-18 11:08:45 -04:00
Read the Web IDE docs to learn how to run [Interactive Terminals through the Web IDE ](../../user/project/web_ide/index.md#interactive-web-terminals-for-the-web-ide ).