Skip to content

Interactive web terminals

DETAILS: Tier: Free, Premium, Ultimate Offering:, Self-managed, GitLab Dedicated

Interactive web terminals give the user access to a terminal in GitLab for 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 shell access to the environment where GitLab Runner is deployed, some security precautions were taken to protect the users.

NOTE: Instance runners on do not provide an interactive web terminal. Follow this issue for progress on adding support. For groups and projects hosted on, interactive web terminals are available when using your own group or project runner.


Two things need to be configured for the interactive web terminal to work:

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:

Debugging a running job

NOTE: Not all executors are supported.

NOTE: The docker executor does not keep running after the build script is finished. At that point, the terminal automatically disconnects and does not wait for the user to finish. Follow this issue for updates on improving this behavior.

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 opens the terminal for the current job. Only the person who started a job can debug it.

Example of job running with terminal available

When selected, a new tab opens to the terminal page where you can access the terminal and type commands like in a standard shell.

terminal of the job

If you have the terminal open and the job has finished with its tasks, the terminal blocks the job from finishing for the duration configured in [session_server].session_timeout until you close the terminal window.

finished job with terminal open

Interactive web terminals for the Web IDE

To run interactive web terminals for the Web IDE, see Web IDE.