github.com/nilium/gitlab-runner@v12.5.0+incompatible/docs/executors/README.md (about) 1 # Executors 2 3 GitLab Runner implements a number of executors that can be used to run your 4 builds in different scenarios. If you are not sure what to select, read the 5 [I am not sure](#i-am-not-sure) section. 6 Visit the [compatibility chart](#compatibility-chart) to find 7 out what features each executor does and does not support. 8 9 To jump into the specific documentation for each executor, visit: 10 11 - [SSH](ssh.md) 12 - [Shell](shell.md) 13 - [Parallels](parallels.md) 14 - [VirtualBox](virtualbox.md) 15 - [Docker](docker.md) 16 - [Docker Machine (auto-scaling)](docker_machine.md) 17 - [Kubernetes](kubernetes.md) 18 - [Custom](custom.md) 19 20 The list of executors above is locked. We no longer are developing or 21 accepting new ones. Please check 22 [CONTRIBUTION.md](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/CONTRIBUTING.md#contributing-a-new-executors) 23 to check the details. 24 25 ## Selecting the executor 26 27 The executors support different platforms and methodologies for building a 28 project. The table below shows the key facts for each executor which will help 29 you decide which executor to use. 30 31 | Executor | SSH | Shell | VirtualBox | Parallels | Docker | Kubernetes | Custom | 32 |:--------------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|---------------:| 33 | Clean build environment for every build | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |conditional (4) | 34 | Reuse previous clone if it exists | ✓ | ✓ | ✗ | ✗ | ✓ | ✗ |conditional (4) | 35 | Migrate runner machine | ✗ | ✗ | partial | partial | ✓ | ✓ |✓ | 36 | Zero-configuration support for concurrent builds | ✗ | ✗ (1) | ✓ | ✓ | ✓ | ✓ |conditional (4) | 37 | Complicated build environments | ✗ | ✗ (2) | ✓ (3) | ✓ (3) | ✓ | ✓ |✓ | 38 | Debugging build problems | easy | easy | hard | hard | medium | medium |medium | 39 40 1. It's possible, but in most cases it is problematic if the build uses services 41 installed on the build machine 42 1. It requires to install all dependencies by hand 43 1. For example using [Vagrant](https://www.vagrantup.com/docs/virtualbox/ "Vagrant documentation for VirtualBox") 44 1. Dependent on what kind of environment you are provisioning. It can be 45 completely isolated or shared between each build. 46 47 ### I am not sure 48 49 #### Shell executor 50 51 **Shell** is the simplest executor to configure. All required dependencies for 52 your builds need to be installed manually on the same machine that the Runner is 53 installed on. 54 55 #### Virtual Machine executor (VirtualBox / Parallels) 56 57 This type of executor allows you to use an already created virtual machine, which 58 is cloned and used to run your build. We offer two full system virtualization 59 options: **VirtualBox** and **Parallels**. They can prove useful if you want to run 60 your builds on different operating systems, since it allows the creation of virtual 61 machines on Windows, Linux, macOS or FreeBSD, then GitLab Runner connects to the 62 virtual machine and runs the build on it. Its usage can also be useful for reducing 63 infrastructure costs. 64 65 #### Docker executor 66 67 A great option is to use **Docker** as it allows a clean build environment, 68 with easy dependency management (all dependencies for building the project can 69 be put in the Docker image). The Docker executor allows you to easily create 70 a build environment with dependent [services](https://docs.gitlab.com/ee/ci/services/README.html), 71 like MySQL. 72 73 #### Docker Machine executor 74 75 The **Docker Machine** is a special version of the **Docker** executor 76 with support for auto-scaling. It works like the normal **Docker** executor 77 but with build hosts created on demand by _Docker Machine_. 78 79 #### Kubernetes executor 80 81 The **Kubernetes** executor allows you to use an existing Kubernetes cluster 82 for your builds. The executor will call the Kubernetes cluster API 83 and create a new Pod (with a build container and services containers) for 84 each GitLab CI job. 85 86 #### SSH executor 87 88 The **SSH** executor is added for completeness, but it's the least supported 89 among all executors. It makes GitLab Runner connect to an external server 90 and runs the builds there. We have some success stories from organizations using 91 this executor, but usually we recommend using one of the other types. 92 93 #### Custom executor 94 95 The **Custom** executor allows you to specify your own execution 96 environments. When GitLab Runner does not provide an executor (for 97 example, LXC containers), you are able to provide your own 98 executables to GitLab Runner to provision and clean up any environment 99 you want to use. 100 101 ## Compatibility chart 102 103 Supported features by different executors: 104 105 | Executor | SSH | Shell |VirtualBox | Parallels | Docker | Kubernetes | Custom | 106 |:---------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|:------:| 107 | Secure Variables | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 108 | GitLab Runner Exec command | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ | 109 | `gitlab-ci.yml`: image | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | 110 | `gitlab-ci.yml`: services | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ | 111 | `gitlab-ci.yml`: cache | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 112 | `gitlab-ci.yml`: artifacts | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 113 | Passing artifacts between stages | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | 114 | Use GitLab Container Registry private images | n/a | n/a | n/a | n/a | ✓ | ✓ | n/a | 115 | Interactive Web terminal | ✗ | ✓ (bash)| ✗ | ✗ | ✓ | ✓ | ✗ | 116 117 Supported systems by different shells: 118 119 | Shells | Bash | Windows Batch | PowerShell | 120 |:-------:|:-----------:|:-------------:|:----------:| 121 | Windows | ✗ (4) | ✓ (2) | ✓ (3) | 122 | Linux | ✓ (1) | ✗ | ✗ | 123 | macOS | ✓ (1) | ✗ | ✗ | 124 | FreeBSD | ✓ (1) | ✗ | ✗ | 125 126 1. Default shell. 127 1. Default shell if no 128 [`shell`](../configuration/advanced-configuration.md#the-runners-section) 129 is specified. 130 1. Default shell when a new GitLab Runner is registered. 131 1. Bash shell is currently not working on Windows out of the box due to 132 [this issue](https://gitlab.com/gitlab-org/gitlab-runner/issues/1515) but is intended 133 to be supported again soon. See the issue for a workaround. 134 135 Supported systems for interactive web terminals by different shells: 136 137 | Shells | Bash | Windows Batch | PowerShell | 138 |:-------:|:-----------:|:-------------:|:----------:| 139 | Windows | ✗ | ✗ | ✗ | 140 | Linux | ✓ | ✗ | ✗ | 141 | macOS | ✓ | ✗ | ✗ | 142 | FreeBSD | ✓ | ✗ | ✗ |