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