Skip to content

gitlab-runner
gitlab-runner
Commit a5eded3a authored by Evan Read's avatar Evan Read
Browse files
Options

Merge branch 'docs/4257-document-generic-executor' into 'master' 

Add custom executor documentation

See merge request !1416
parents caf543de 6eadf2f8
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 459 additions and 20 deletions
docs/configuration/advanced-configuration.md
View file @ a5eded3a
......@@ -510,6 +510,27 @@ Like in the standard cron configuration file, the fields can contain single
values, ranges, lists and asterisks. A detailed description of the syntax
can be found [here][cronvendor].
## The `[runners.custom]` section
Define configuration for the [custom
executor](../executors/custom.md).
| Parameter | Type | Required | Description |
|-------------------------|--------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `config_exec` | string | ✗ | Path to an executable to allow the user to override some configuration settings before the build starts. These values will override the ones set inside of the [`[[runners]]`](#the-runners-section) section. [The custom executor documentation](../executors/custom.md#config) has the full list. |
| `config_args` | string array | ✗ | First set of arguments passed to the `config_exec` executable. |
| `config_exec_timeout` | integer | ✗ | Timeout in seconds for `config_exec` to finish execution. Default to 1 hour. |
| `prepare_exec` | string | ✗ | Path to an executable to prepare the environment. |
| `prepare_args` | string array | ✗ | First set of arguments passed to the `prepare_exec` executable. |
| `prepare_exec_timeout` | integer | ✗ | Timeout in seconds for `prepare_exec` to finish execution. Default to 1 hour. |
| `run_exec` | string | ✓ | Path to an executable to run scripts in the environments. For example, the clone and build script. |
| `run_args` | string array | ✗ | First set of arguments passed to the `run_exec` executable. |
| `cleanup_exec` | string | ✗ | Path to an executable to clean up the environment. |
| `cleanup_args` | string array | ✗ | First set of arguments passed to the `cleanup_exec` executable. |
| `cleanup_exec_timeout` | integer | ✗ | Timeout in seconds for `cleanup_exec` to finish execution. Default to 1 hour. |
| `graceful_kill_timeout` | integer | ✗ | Time to wait in seconds for `prepare_exec` and `cleanup_exec` if they are terminated (for example, during build cancellation). After this timeout, the process is killed. Defaults to 10 minutes. |
| `force_kill_timeout` | integer | ✗ | Time to wait in seconds after the kill signal is sent to the script. Defaults to 10 minutes. |
## The `[runners.cache]` section
> Introduced in GitLab Runner 1.1.0.
......
docs/executors/README.md
View file @ a5eded3a
......@@ -15,6 +15,7 @@ To jump into the specific documentation for each executor, visit:
- [Docker](docker.md)
- [Docker Machine (auto-scaling)](docker_machine.md)
- [Kubernetes](kubernetes.md)
- [Custom](custom.md)
The list of executors above is locked. We no longer are developing or
accepting new ones. Please check
......@@ -27,19 +28,21 @@ The executors support different platforms and methodologies for building a
project. The table below shows the key facts for each executor which will help
you decide which executor to use.
| Executor | SSH | Shell | VirtualBox | Parallels | Docker | Kubernetes |
|:--------------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|
| Clean build environment for every build | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |
| Reuse previous clone if it exists | ✓ | ✓ | ✗ | ✗ | ✓ | ✗ |
| Migrate runner machine | ✗ | ✗ | partial | partial | ✓ | ✓ |
| Zero-configuration support for concurrent builds | ✗ | ✗ (1) | ✓ | ✓ | ✓ | ✓ |
| Complicated build environments | ✗ | ✗ (2) | ✓ (3) | ✓ (3) | ✓ | ✓ |
| Debugging build problems | easy | easy | hard | hard | medium | medium |
| Executor | SSH | Shell | VirtualBox | Parallels | Docker | Kubernetes | Custom |
|:--------------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|---------------:|
| Clean build environment for every build | ✗ | ✗ | ✓ | ✓ | ✓ | ✓ |conditional (4) |
| Reuse previous clone if it exists | ✓ | ✓ | | ✗ | ✓ | ✗ |conditional (4) |
| Migrate runner machine | ✗ | ✗ | partial | partial | ✓ | ✓ |✓ |
| Zero-configuration support for concurrent builds | ✗ | ✗ (1) | ✓ | ✓ | ✓ | ✓ |conditional (4) |
| Complicated build environments | ✗ | ✗ (2) | ✓ (3) | ✓ (3) | ✓ | ✓ |✓ |
| Debugging build problems | easy | easy | hard | hard | medium | medium |medium |
1. It's possible, but in most cases it is problematic if the build uses services
installed on the build machine
1. It requires to install all dependencies by hand
1. For example using [Vagrant](https://www.vagrantup.com/docs/virtualbox/ "Vagrant documentation for VirtualBox")
1. Dependent on what kind of environment you are provisioning. It can be
completely isolated or shared between each build.
### I am not sure
......@@ -87,22 +90,30 @@ among all executors. It makes GitLab Runner connect to an external server
and runs the builds there. We have some success stories from organizations using
this executor, but usually we recommend using one of the other types.
#### Custom executor
The **Custom** executor allows you to specify your own execution
environments. When GitLab Runner does not provide an executor (for
example, LXC containers), you are able to provide your own
executables to GitLab Runner to provision and clean up any environment
you want to use.
## Compatibility chart
Supported features by different executors:
| Executor | SSH | Shell | VirtualBox | Parallels | Docker | Kubernetes |
|:---------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|
| Secure Variables | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| GitLab Runner Exec command | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ |
| gitlab-ci.yml: image | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ |
| gitlab-ci.yml: services | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ |
| gitlab-ci.yml: cache | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| gitlab-ci.yml: artifacts | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Absolute paths: caching, artifacts | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ |
| Passing artifacts between stages | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Use GitLab Container Registry private images | n/a | n/a | n/a | n/a | ✓ | ✓ |
| Interactive Web terminal | ✗ | ✓ (bash)| ✗ | ✗ | ✓ | ✓ |
| Executor | SSH | Shell |VirtualBox | Parallels | Docker | Kubernetes | Custom |
|:---------------------------------------------|:----:|:-------:|:----------:|:---------:|:------:|:----------:|:------:|
| Secure Variables | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| GitLab Runner Exec command | ✗ | ✓ | ✗ | ✗ | ✓ | ✓ | ✓ |
| gitlab-ci.yml: image | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ |
| gitlab-ci.yml: services | ✗ | ✗ | ✗ | ✗ | ✓ | ✓ | ✗ |
| gitlab-ci.yml: cache | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| gitlab-ci.yml: artifacts | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Absolute paths: caching, artifacts | ✗ | ✗ | ✗ | ✗ | ✗ | ✓ | ✗ |
| Passing artifacts between stages | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| Use GitLab Container Registry private images | n/a | n/a | n/a | n/a | ✓ | ✓ | n/a |
| Interactive Web terminal | ✗ | ✓ (bash)| ✗ | ✗ | ✓ | ✓ | ✗ |
Supported systems by different shells:
......
docs/executors/custom.md 0 → 100644
View file @ a5eded3a
This diff is collapsed.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment