1---
2stage: Verify
3group: Runner
4info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
5---
6
7# The Shell executor
8
9The Shell executor is a simple executor that you use to execute builds
10locally on the machine where GitLab Runner is installed. It supports all systems on
11which the Runner can be installed. That means that it's possible to use scripts
12generated for Bash, PowerShell Core, Windows PowerShell, and Windows Batch (deprecated).
13
14NOTE:
15Always use the [latest version of Git available](https://git-scm.com/download/). Additionally, GitLab Runner will use
16the `git lfs` command if [Git LFS](https://git-lfs.github.com) is installed on the machine,
17so ensure Git LFS is up-to-date when GitLab Runner will run using the shell executor.
18
19## Overview
20
21The scripts can be run as unprivileged user if the `--user` is added to the
22[`gitlab-runner run` command](../commands/index.md#gitlab-runner-run). This feature is only supported by Bash.
23
24The source project is checked out to:
25`<working-directory>/builds/<short-token>/<concurrent-id>/<namespace>/<project-name>`.
26
27The caches for project are stored in
28`<working-directory>/cache/<namespace>/<project-name>`.
29
30Where:
31
32- `<working-directory>` is the value of `--working-directory` as passed to the
33  `gitlab-runner run` command or the current directory where the Runner is
34  running
35- `<short-token>` is a shortened version of the Runner's token (first 8 letters)
36- `<concurrent-id>` is a unique number, identifying the local job ID on the
37  particular Runner in context of the project
38- `<namespace>` is the namespace where the project is stored on GitLab
39- `<project-name>` is the name of the project as it is stored on GitLab
40
41To overwrite the `<working-directory>/builds` and `<working-directory/cache`
42specify the `builds_dir` and `cache_dir` options under the `[[runners]]` section
43in [`config.toml`](../configuration/advanced-configuration.md).
44
45## Running as unprivileged user
46
47If GitLab Runner is installed on Linux from the [official `.deb` or `.rpm`
48packages](https://packages.gitlab.com/runner/gitlab-runner), the installer will try to use the `gitlab_ci_multi_runner`
49user if found. If it is not found, it will create a `gitlab-runner` user and use
50this instead.
51
52All shell builds will be then executed as either the `gitlab-runner` or
53`gitlab_ci_multi_runner` user.
54
55In some testing scenarios, your builds may need to access some privileged
56resources, like Docker Engine or VirtualBox. In that case you need to add the
57`gitlab-runner` user to the respective group:
58
59```shell
60usermod -aG docker gitlab-runner
61usermod -aG vboxusers gitlab-runner
62```
63
64## Selecting your shell
65
66GitLab Runner [supports certain shells](../shells/index.md). To select a shell, specify it in your `config.toml` file. For example:
67
68```toml
69...
70[[runners]]
71  name = "shell executor runner"
72  executor = "shell"
73  shell = "powershell"
74...
75```
76
77## Security
78
79Generally it's unsafe to run tests with shell executors. The jobs are run with
80the user's permissions (`gitlab-runner`) and can "steal" code from other
81projects that are run on this server. Use it only for running builds on a
82server you trust and own.
83
84## Terminating and killing processes
85
86The shell executor starts the script for each job in a new process. On
87UNIX systems, it sets the main process as a [process
88group](https://www.informit.com/articles/article.aspx?p=397655&seqNum=6).
89
90GitLab Runner terminates processes when:
91
92- A job [times out](https://docs.gitlab.com/ee/ci/pipelines/settings.html#timeout).
93- A job is canceled.
94
95### GitLab 13.0 and earlier
96
97On UNIX systems `gitlab-runner` sends a `SIGKILL` to the process to
98terminate it, because the child processes belong to the same process
99group the signal is also sent to them. Windows sends a `taskkill /F /T`.
100
101### GitLab 13.1 and later
102
103On UNIX system `gitlab-runner` sends `SIGTERM` to the process and its
104child processes, and after 10 minutes sends `SIGKILL`. This allows for
105graceful termination for the process. Windows don't have a `SIGTERM`
106equivalent, so the kill process is sent twice. The second is sent after
10710 minutes.
108