Commit 0c26733f authored by Suzanne Selhorn's avatar Suzanne Selhorn Committed by Marcel Amirault

Docs: Revamp Runner home page

parent ebcdf469
......@@ -5,166 +5,176 @@ group: Runner
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
---
# GitLab Runner Docs
# GitLab Runner
GitLab Runner is the lightweight, highly-scalable agent that runs your build jobs
and sends the results back to a GitLab instance.
GitLab Runner is an application that works with GitLab CI/CD to run jobs in a pipeline.
GitLab Runner works in conjunction with GitLab CI/CD, the open-source
continuous integration service included with GitLab.
You can choose to [**install**](install/index.md) the GitLab Runner application
on infrastructure that you own or manage. If you do, you should install
GitLab Runner on a machine that's separate from the one that hosts the GitLab instance.
This documentation includes details about installing and setting up GitLab Runner,
and registering and configuring individual runners.
GitLab Runner is open-source and written in [Go](https://golang.org). It can be run
as a single binary; no language-specific requirements are needed.
If you already have runners set up and you need help using them
in your GitLab instance, the information you need may be in the
[main GitLab documentation](https://docs.gitlab.com/ee/ci/README.html).
You can install GitLab Runner on several different supported operating systems.
Other operating systems may also work, as long as you can compile a Go
binary on them.
For example, visit the main GitLab documentation to learn more about:
GitLab Runner can also run inside a Docker container or be deployed into a Kubernetes cluster.
- [How to configure a runner in GitLab](https://docs.gitlab.com/ee/ci/runners/README.html).
- [How to run a CI/CD job in a Docker container](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html).
- [How GitLab CI/CD works](https://docs.gitlab.com/ee/ci/README.html).
View some [best practices](best_practice/index.md) for how to use and administer GitLab Runner.
## Requirements
## GitLab Runner versions
GitLab Runner is an open-source project written in [Go](https://golang.org) and can be run as a single binary. No
language specific requirements are needed.
GitLab Runner should be the same version as GitLab. Older runners may still work
with newer GitLab versions, and vice versa. However, features may be not available or work properly
if a version difference exists.
It is designed to run on the GNU/Linux, macOS, and Windows operating systems.
Other operating systems might work as long as you can compile a Go
binary on them.
Backward compatibility is guaranteed between minor version updates. However, sometimes minor
version updates of GitLab can introduce new features that require GitLab Runner to be on the same minor
version.
If you want to [use Docker](executors/docker.md), install the latest version.
GitLab Runner requires a minimum of Docker `v1.13.0`.
## Runner registration
## Features
After you install the application, you [**register**](register/index.md)
individual runners. Runners are the agents that run the CI/CD jobs that come from GitLab.
- Allows:
- Running multiple jobs concurrently.
- Using multiple tokens with multiple servers (even per-project).
- Limiting number of concurrent jobs per-token.
- Jobs can be run:
- Locally.
- Using Docker containers.
- Using Docker containers and executing job over SSH.
- Using Docker containers with autoscaling on different clouds and virtualization hypervisors.
- Connecting to a remote SSH server.
- Is written in Go and distributed as single binary without any other requirements.
- Supports Bash and Windows PowerShell.
- Works on GNU/Linux, macOS, and Windows (pretty much anywhere you can run Docker).
- Allows customization of the job running environment.
- Automatic configuration reload without restart.
- Easy to use setup with support for Docker, Docker-SSH, Parallels, or SSH running environments.
- Enables caching of Docker containers.
- Easy installation as a service for GNU/Linux, macOS, and Windows.
- Embedded Prometheus metrics HTTP server.
- Referee workers to monitor and pass Prometheus metrics and other job-specific data to GitLab.
When you register a runner, you are setting up communication between your
GitLab instance and the machine where GitLab Runner is installed.
## Compatibility with GitLab versions
Runners usually process jobs on the same machine where you installed GitLab Runner.
However, you can also have a runner process jobs in a container,
in a Kubernetes cluster, or in auto-scaled instances in the cloud.
The GitLab Runner version should be in sync with the GitLab version. Older runners may still work
with newer GitLab versions (and vice versa). However, features may be not available or work properly
if there's a version difference.
### Executors
Backward compatibility is guaranteed between minor version updates. However, be aware that minor
version updates of GitLab can introduce new features that require the Runner to be on the same minor
version.
When you register a runner, you must choose an executor.
## Install GitLab Runner
An [**executor**](executors/README.md) determines the environment each job runs in.
GitLab Runner can be [installed](install/index.md) and used on GNU/Linux, macOS, FreeBSD, and Windows.
You can install it using Docker, download the binary manually or use the
repository for rpm/deb packages that GitLab offers. Below you can find
information on the different installation methods:
For example:
- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat (preferred)](install/linux-repository.md).
- [Install on GNU/Linux manually (advanced)](install/linux-manually.md).
- [Install on macOS](install/osx.md).
- [Install on Windows](install/windows.md).
- [Install as a Docker service](install/docker.md).
- [Install in autoscaling mode using Docker machine](executors/docker_machine.md).
- [Install on FreeBSD](install/freebsd.md).
- [Install on Kubernetes](install/kubernetes.md).
- [Install the nightly binary manually (development)](install/bleeding-edge.md).
- If you want your CI/CD job to run PowerShell commands, you might install GitLab
Runner on a Windows server and then register a runner that uses the shell executor.
- If you want your CI/CD job to run commands in a custom Docker container,
you might install GitLab Runner on a Linux server and register a runner that uses
the Docker executor.
## Register GitLab Runner
These are only a few of the possible configurations. You can install GitLab Runner
on a virtual machine and have it use another virtual machine as an executor.
Once GitLab Runner is installed, you need to register it with GitLab.
When you install GitLab Runner in a Docker container and choose the
[Docker executor](https://docs.gitlab.com/ee/ci/docker/using_docker_images.html)
to run your jobs, it's sometimes referred to as a "Docker-in-Docker" configuration.
Learn how to [register a GitLab Runner](register/index.md).
### Who has access to runners in the GitLab UI
## Using GitLab Runner
Before you register a runner, you should determine if everyone in GitLab
should have access to it, or if you want to limit it to a specific GitLab group or project.
- See the [commands documentation](commands/README.md).
- See [best practice documentation](best_practice/index.md).
There are three types of runners, based on who you want to have access:
## Selecting the executor
- [Shared runners](https://docs.gitlab.com/ee/ci/runners/README.html#shared-runners) are for use by all projects
- [Group runners](https://docs.gitlab.com/ee/ci/runners/README.html#group-runners) are for all projects and subgroups in a group
- [Specific runners](https://docs.gitlab.com/ee/ci/runners/README.html#specific-runners) are for individual projects
GitLab Runner implements a number of [executors](executors/README.md) that can be used to run your
builds in different scenarios. If you are not sure what to select, read the
[I am not sure](executors/README.md#i-am-not-sure) section.
Visit the [compatibility chart](executors/README.md#compatibility-chart) to find
out what features each executor supports and what not.
When you register a runner, you specify a token for the GitLab instance, group, or project.
This is how the runner knows which projects it's available for.
To jump into the specific documentation of each executor, see:
### Tags
- [Shell](executors/shell.md).
- [Docker](executors/docker.md).
- [Docker Machine and Docker Machine SSH (autoscaling)](executors/docker_machine.md).
- [Parallels](executors/parallels.md).
- [VirtualBox](executors/virtualbox.md).
- [SSH](executors/ssh.md).
- [Kubernetes](executors/kubernetes.md).
When you register a runner, you can add [**tags**](https://docs.gitlab.com/ee/ci/yaml/README.html#tags) to it.
No development of new executors is planned and we are not accepting
contributions for new ones. Please check
[CONTRIBUTION.md](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/CONTRIBUTING.md#contributing-a-new-executors)
for details.
When a CI/CD job runs, it knows which runner to use by looking at the assigned tags.
## Configuring GitLab Runner
For example, if a runner has the `ruby` tag, you would add this code to
your project's `.gitlab-ci.yml` file:
See information on [configuring GitLab Runner](configuration/index.md), and:
```yaml
job:
tags:
- ruby
```
- [Advanced configuration options](configuration/advanced-configuration.md): Learn how to use the [TOML](https://github.com/toml-lang/toml) configuration file that GitLab Runner uses.
- [Use self-signed certificates](configuration/tls-self-signed.md): Configure certificates that are used to verify TLS peer when connecting to the GitLab server.
- [Autoscaling using Docker machine](configuration/autoscale.md): Execute jobs on machines that are created on demand using Docker machine.
- [Autoscaling GitLab Runner on AWS](configuration/runner_autoscale_aws/index.md)
- [The init system of GitLab Runner](configuration/init.md): Learn how the Runner installs its init service files based on your operating system.
- [Supported shells](shells/index.md): Learn what shell script generators are supported that allow to execute builds on different systems.
- [Security considerations](security/index.md): Be aware of potential security implications when running your jobs with GitLab Runner.
- [Runner monitoring](monitoring/README.md): Learn how to monitor the Runner's behavior.
- [Cleanup the Docker images automatically](https://gitlab.com/gitlab-org/gitlab-runner-docker-cleanup): A simple Docker application that automatically garbage collects the GitLab Runner caches and images when running low on disk space.
- [Configure GitLab Runner to run behind a proxy](configuration/proxy.md): Learn how to set up a Linux proxy and configure GitLab Runner. Especially useful for the Docker executor.
- [Feature Flags](configuration/feature-flags.md): Learn how to use feature flags to get access to features in beta stage or to enable breaking changes before the full deprecation and replacement is handled.
- [Configure Session Server](configuration/advanced-configuration.md#the-session_server-section): Learn how to configure a session server for interacting with jobs the Runner is responsible for.
When the job runs, it uses the runner with the `ruby` tag.
## Troubleshooting
## Configuring runners
Read the [FAQ](faq/README.md) for troubleshooting common issues.
You can [**configure**](configuration/advanced-configuration.md)
the runner by editing the `config.toml` file. This is a file that is installed during the runner installation process.
## Release process
In this file you can edit settings for a specific runner, or for all runners.
The description of release process of the GitLab Runner project can be
found in
[PROCESS.md](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/PROCESS.md)
You can specify settings like logging and cache. You can set concurrency,
memory, CPU limits, and more.
## Contributing
## Monitoring runners
You can use Prometheus to [**monitor**](monitoring/README.md) your runners.
You can view things like the number of currently-running jobs and how
much CPU your runners are using.
## Use a runner to run your job
After a runner is configured and available for your project, your
[CI/CD](https://docs.gitlab.com/ee/ci/README.html) jobs can use the runner.
Specify the name of the runner or its tags in your
[`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/README.html) file.
Then, when you commit to your repository, the pipeline runs, and
the runner's executor processes the commands.
Contributions are welcome, see [`CONTRIBUTING.md`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/CONTRIBUTING.md) for more details.
## Runners on GitLab.com
## Development
If you use GitLab.com, GitLab [manages runners for you](https://docs.gitlab.com/ee/user/gitlab_com/index.html#shared-runners).
These runners are enabled for all projects, though
[you can disable them](https://docs.gitlab.com/ee/ci/runners/README.html#disable-shared-runners).
See the [development documentation](development/README.md) to hack on GitLab
Runner.
If you don't want to use runners managed by GitLab, you can install GitLab Runner and
register your own runners on GitLab.com.
If you're a reviewer of GitLab Runner project, then please take a moment to read the
## Features
GitLab Runner has the following features.
- Run multiple jobs concurrently.
- Use multiple tokens with multiple servers (even per-project).
- Limit the number of concurrent jobs per-token.
- Jobs can be run:
- Locally.
- Using Docker containers.
- Using Docker containers and executing job over SSH.
- Using Docker containers with autoscaling on different clouds and virtualization hypervisors.
- Connecting to a remote SSH server.
- Is written in Go and distributed as single binary without any other requirements.
- Supports Bash and Windows PowerShell.
- Works on GNU/Linux, macOS, and Windows (pretty much anywhere you can run Docker).
- Allows customization of the job running environment.
- Automatic configuration reload without restart.
- Easy to use setup with support for Docker, Docker-SSH, Parallels, or SSH running environments.
- Enables caching of Docker containers.
- Easy installation as a service for GNU/Linux, macOS, and Windows.
- Embedded Prometheus metrics HTTP server.
- Referee workers to monitor and pass Prometheus metrics and other job-specific data to GitLab.
## Troubleshooting
Learn how to [troubleshoot](faq/README.md) common issues.
## Contributing
Contributions are welcome. See [`CONTRIBUTING.md`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/CONTRIBUTING.md)
and the [development documentation](development/README.md) for details.
If you're a reviewer of GitLab Runner project, take a moment to read the
[Reviewing GitLab Runner](development/reviewing-gitlab-runner.md) document.
You can also review [the release process for the GitLab Runner project](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/PROCESS.md).
## Changelog
See the [CHANGELOG](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/CHANGELOG.md) to view recent changes.
## License
This code is distributed under the MIT license, see the [LICENSE](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/LICENSE) file.
This code is distributed under the MIT license. View the [LICENSE](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/LICENSE) file.
......@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Old GitLab Runner URLs
NOTE: **Note:**
Take a look at the [compatibility section](../index.md#compatibility-with-gitlab-versions) to check the Runner's compatibility
Take a look at the [compatibility section](../index.md#gitlab-runner-versions) to check the Runner's compatibility
with your version of GitLab.
In GitLab Runner 10, the name of the executable was renamed from
......
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