Commit a0b870ef authored by Achilleas Pipinellis (OOO)'s avatar Achilleas Pipinellis (OOO) 🌴

Merge branch 'docs/cleanup' into 'master'

Perform some documentation cleanup

See merge request !491
parents 39837bca 0f162ac3
## How to configure runner for GitLab CE integration tests (uses confined Docker executor)
# How to configure GitLab Runner for GitLab CE integration tests
### 1. Register the runner
We will register the Runner using a confined Docker executor.
The registration token can be found at `https://gitlab.com/project_namespace/project_name/runners`.
You can export it as a variable and run the command below as is:
......@@ -16,8 +16,6 @@ gitlab-ci-multi-runner register \
--docker-postgres latest --docker-redis latest
```
----
You now have a GitLab CE integration testing instance with bundle caching.
Push some commits to test it.
......
# The Kubernetes executor (**EXPERIMENTAL**)
# The Kubernetes executor
>**Note:**
This executor is **EXPERIMENTAL**.
GitLab Runner can use Kubernetes to run builds on a kubernetes cluster. This is
possible with the use of the **Kubernetes** executor.
......@@ -12,13 +15,6 @@ yaml. The names for these containers are as follows:
- The build container is `build`
- The services containers are `svc-X` where `X` is `[0-9]+`
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Workflow
The Kubernetes executor divides the build into multiple steps:
......
......@@ -5,18 +5,6 @@ locally to the machine that the Runner is installed. It supports all systems on
which the Runner can be installed. That means that it's possible to use scripts
generated for Bash, Windows PowerShell and Windows Batch.
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Overview](#overview)
- [Running as unprivileged user](#running-as-unprivileged-user)
- [Security](#security)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Overview
The scripts can be run as unprivileged user if the `--user` is added to the
......
......@@ -7,17 +7,6 @@ is currently not supported.
This is a simple executor that allows you to execute builds on a remote machine
by executing commands over SSH.
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Overview](#overview)
- [Security](#security)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Overview
To use the SSH executor you need to specify `executor = "ssh"` under the
......
# VirtualBox
> Note: The Parallels executor works the same as the VirtualBox executor. The
>**Note:**
The Parallels executor works the same as the VirtualBox executor. The
caching feature is currently not supported.
VirtualBox allows you to use VirtualBox's virtualization to provide a clean
......@@ -8,19 +9,6 @@ build environment for every build. This executor supports all systems that can
be run on VirtualBox. The only requirement is that the virtual machine exposes
its SSH server and provide a bash-compatible shell.
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Overview](#overview)
- [Create a new base virtual machine](#create-a-new-base-virtual-machine)
- [Create a new Runner](#create-a-new-runner)
- [How it works](#how-it-works)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Overview
The project's source code is checked out to: `~/builds/<namespace>/<project-name>`.
......
# FAQ
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [1. Where are logs stored when run as a service?](#1-where-are-logs-stored-when-run-as-a-service)
- [2. Run in `--debug` mode](#2-run-in---debug-mode)
- [3. I get a PathTooLongException during my builds on Windows](#3-i-get-a-pathtoolongexception-during-my-builds-on-windows)
- [4. I'm seeing `x509: certificate signed by unknown authority`](#4-im-seeing-x509-certificate-signed-by-unknown-authority)
- [5. I get `Permission Denied` when accessing the `/var/run/docker.sock`](#5-i-get-permission-denied-when-accessing-the-varrundockersock)
- [6. The Docker executor gets timeout when building Java project.](#6-the-docker-executor-gets-timeout-when-building-java-project)
- [7. I get 411 when uploading artifacts.](#7-i-get-411-when-uploading-artifacts)
- [8. I can't run Windows BASH scripts; I'm getting `The system cannot find the batch label specified - buildscript`.](#8-i-cant-run-windows-bash-scripts-im-getting-the-system-cannot-find-the-batch-label-specified---buildscript)
- [9. My gitlab runner is on Windows. How can I get colored output on the web terminal?](#9-my-gitlab-runner-is-on-windows-how-can-i-get-colored-output-on-the-web-terminal)
- [10. "warning: You appear to have cloned an empty repository."](#10-warning-you-appear-to-have-cloned-an-empty-repository)
- [11. `"launchctl" failed: exit status 112, Could not find domain for`](#11-launchctl-failed-exit-status-112-could-not-find-domain-for)
- [12. `Failed to authorize rights (0x1) with status: -60007.`](#12-failed-to-authorize-rights-0x1-with-status--60007)
- [13. `The service did not start due to a logon failure` error when starting service on Windows](#13-the-service-did-not-start-due-to-a-logon-failure-error-when-starting-service-on-windows)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
Some Frequently Asked Questions about GitLab Runner.
## 1. Where are logs stored when run as a service?
......@@ -241,4 +224,4 @@ and the service should be started properly.
[microsoft-manually-set-seservicelogonright]: https://technet.microsoft.com/en-us/library/dn221981
[microsoft-ntrights-download]: https://www.microsoft.com/en-us/download/details.aspx?id=17657
[microsoft-ntrights-usage-on-win7]: https://technet.microsoft.com/en-us/library/dd548356(WS.10).aspx
\ No newline at end of file
[microsoft-ntrights-usage-on-win7]: https://technet.microsoft.com/en-us/library/dd548356(WS.10).aspx
......@@ -5,22 +5,6 @@
For an overview of the auto-scale architecture, take a look at the
[comprehensive documentation on auto-scaling](../configuration/autoscale.md).
---
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents** *generated with [DocToc](https://github.com/thlorenz/doctoc)*
- [Prepare the environment](#prepare-the-environment)
- [Prepare the Docker Registry and Cache Server](#prepare-the-docker-registry-and-cache-server)
- [Install Docker Registry](#install-docker-registry)
- [Install the cache server](#install-the-cache-server)
- [Configure GitLab Runner](#configure-gitlab-runner)
- [Upgrading the Runner](#upgrading-the-runner)
- [Manage the Docker Machines](#manage-the-docker-machines)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Prepare the environment
In order to use the auto-scale feature, Docker and GitLab Runner must be
......
## Bleeding edge releases (development)
# Bleeding edge releases
### Download the standalone binaries
>**Note:**
These are the latest, probably untested releases of GitLab Runner built straight
from `master` branch. Use at your own risk.
## Download the standalone binaries
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-linux-386
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-linux-amd64
......@@ -13,13 +17,13 @@
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-freebsd-amd64
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/binaries/gitlab-ci-multi-runner-freebsd-arm
You can then run the runner with:
You can then run the Runner with:
```bash
chmod +x gitlab-ci-multi-runner-linux-amd64
./gitlab-ci-multi-runner-linux-amd64 run
```
### Download one of the packages for Debian or Ubuntu
## Download one of the packages for Debian or Ubuntu
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/deb/gitlab-ci-multi-runner_i386.deb
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/deb/gitlab-ci-multi-runner_amd64.deb
......@@ -31,7 +35,7 @@ You can then install it with:
dpkg -i gitlab-ci-multi-runner_386.deb
```
### Download one of the packages for RedHat or CentOS
## Download one of the packages for RedHat or CentOS
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/rpm/gitlab-ci-multi-runner_i686.rpm
* https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/master/rpm/gitlab-ci-multi-runner_amd64.rpm
......@@ -43,7 +47,7 @@ You can then install it with:
rpm -i gitlab-ci-multi-runner_386.rpm
```
### Download any other tagged release
## Download any other tagged release
Simply replace `master` with either `tag` (v0.2.0 or 0.4.2) or `latest` (the latest
stable). For a list of tags see <https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tags>.
......
## Run gitlab-runner in a container
# Run GitLab Runner in a container
### Docker image installation and configuration
This is how you can run GitLab Runner inside a Docker container.
## Docker image installation and configuration
Install Docker first:
......@@ -8,7 +10,7 @@ Install Docker first:
curl -sSL https://get.docker.com/ | sh
```
We need to mount a config volume into our gitlab-runner container to
We need to mount a config volume into our `gitlab-runner` container to
be used for configs and other resources:
```bash
......@@ -18,7 +20,7 @@ docker run -d --name gitlab-runner --restart always \
gitlab/gitlab-runner:latest
```
OR you can use a config container to mount your custom data volume:
Or, you can use a config container to mount your custom data volume:
```bash
docker run -d --name gitlab-runner-config \
......@@ -31,7 +33,7 @@ docker run -d --name gitlab-runner --restart always \
gitlab/gitlab-runner:latest
```
If you plan on using Docker as the method of spawning runners, you will need to
If you plan on using Docker as the method of spawning Runners, you will need to
mount your docker socket like this:
```bash
......@@ -66,7 +68,7 @@ The runner should is started already and you are ready to build your projects!
Make sure that you read the [FAQ](../faq/README.md) section which describes
some of the most common problems with GitLab Runner.
### Update
## Update
Pull the latest version:
......@@ -92,7 +94,7 @@ docker run -d --name gitlab-runner --restart always \
**Note**: you need to use the same method for mounting you data volume as you
did originally (`-v /srv/gitlab-runner/config:/etc/gitlab-runner` or `--volumes-from gitlab-runner`)
### Installing Trusted SSL Server Certificates
## Installing trusted SSL server certificates
If your GitLab CI server is using self-signed SSL certificates then you should
make sure the GitLab CI server certificate is trusted by the gitlab-ci-multi-runner
......@@ -108,7 +110,7 @@ want gitlab-ci-multi-runner to trust. The gitlab-ci-multi-runner container will
import the `ca.crt` file on startup so if your container is already running you
may need to restart it for the changes to take effect.
### Alpine Linux
## Alpine Linux
You can also use alternative [Alpine Linux](https://www.alpinelinux.org/) based image with much smaller footprint:
```
......@@ -120,7 +122,7 @@ gitlab/gitlab-runner alpine 7c431ac8f30f 13 hours ago
The original `gitlab/gitlab-runner:latest` is based on Ubuntu 14.04 LTS.
### SELinux
## SELinux
Some distributions (CentOS, RedHat, Fedora) use SELinux by default to enhance the security of the underlying system.
......@@ -135,10 +137,10 @@ Install the `selinux-dockersock` and to resolve the issue: https://github.com/dp
1. Run docker with `:Z` on volumes:
```bash
docker run -d --name gitlab-runner --restart always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
gitlab/gitlab-runner:latest
docker run -d --name gitlab-runner --restart always \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /srv/gitlab-runner/config:/etc/gitlab-runner:Z \
gitlab/gitlab-runner:latest
```
More information about the cause and resolution can be found here:
......
# Install on FreeBSD
Create gitlab-runner user and group:
```bash
sudo pw group add -n gitlab-runner
sudo pw user add -n gitlab-runner -g gitlab-runner -s /usr/local/bin/bash
sudo mkdir /home/gitlab-runner
sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner
```
Download the binary for your system:
```bash
sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-amd64
sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-386
```
Give it permissions to execute:
```bash
sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
```
Create empty log file with correct permissions:
```bash
sudo touch /var/log/gitlab_runner.log && sudo chown gitlab-runner:gitlab-runner /var/log/gitlab_runner.log
```
Create rc.d directory in case it does not exist:
```bash
mkdir -p /usr/local/etc/rc.d
```
Create rc.d script:
```bash
sudo bash -c 'cat > /usr/local/etc/rc.d/gitlab_runner' << "EOF"
#!/bin/sh
# PROVIDE: gitlab_runner
# REQUIRE: DAEMON NETWORKING
# BEFORE:
# KEYWORD:
. /etc/rc.subr
name="gitlab_runner"
rcvar="gitlab_runner_enable"
load_rc_config $name
user="gitlab-runner"
user_home="/home/gitlab-runner"
command="/usr/local/bin/gitlab-ci-multi-runner run"
pidfile="/var/run/${name}.pid"
start_cmd="gitlab_runner_start"
stop_cmd="gitlab_runner_stop"
status_cmd="gitlab_runner_status"
gitlab_runner_start()
{
export USER=${user}
export HOME=${user_home}
if checkyesno ${rcvar}; then
cd ${user_home}
/usr/sbin/daemon -u ${user} -p ${pidfile} ${command} > /var/log/gitlab_runner.log 2>&1
fi
}
gitlab_runner_stop()
{
if [ -f ${pidfile} ]; then
kill `cat ${pidfile}`
fi
}
gitlab_runner_status()
{
if [ ! -f ${pidfile} ] || kill -0 `cat ${pidfile}`; then
echo "Service ${name} is not running."
else
echo "${name} appears to be running."
fi
}
run_rc_command $1
EOF
```
Make it executable:
```bash
sudo chmod +x /usr/local/etc/rc.d/gitlab_runner
```
Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
```bash
sudo -u gitlab-runner -H /usr/local/bin/gitlab-ci-multi-runner register
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com):
Please enter the gitlab-ci token for this runner:
Please enter the gitlab-ci description for this runner:
[name]:
Please enter the gitlab-ci tags for this runner (comma separated):
Registering runner... succeeded
Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
shell
Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded!
```
Enable gitlab-runner service and start it:
```bash
sudo sysrc -f /etc/rc.conf "gitlab_runner_enable=YES"
sudo service gitlab_runner start
```
If you don't want to enable gitlab-runner server to restart after reboot, you can start it:
```bash
sudo service gitlab_runner onestart
```
**The FreeBSD version is also available from [Bleeding edge](bleeding-edge.md)**
Make sure that you read the [FAQ](../faq/README.md) section which describes
some of the most common problems with GitLab Runner.
>**Notes:**
- The FreeBSD version is also available as a [bleeding edge](bleeding-edge.md)
release.
- Make sure that you read the [FAQ](../faq/README.md) section which describes
some of the most common problems with GitLab Runner.
Here are the steps to install and configure GitLab Runner under FreeBSD:
1. Create the `gitlab-runner` user and group:
```bash
sudo pw group add -n gitlab-runner
sudo pw user add -n gitlab-runner -g gitlab-runner -s /usr/local/bin/bash
sudo mkdir /home/gitlab-runner
sudo chown gitlab-runner:gitlab-runner /home/gitlab-runner
```
1. Download the binary for your system:
```bash
# For amd64
sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-amd64
# For i386
sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-freebsd-386
```
1. Give it permissions to execute:
```bash
sudo chmod +x /usr/local/bin/gitlab-ci-multi-runner
```
1. Create an empty log file with correct permissions:
```bash
sudo touch /var/log/gitlab_runner.log && sudo chown gitlab-runner:gitlab-runner /var/log/gitlab_runner.log
```
1. Create the `rc.d` directory in case it doesn't exist:
```bash
mkdir -p /usr/local/etc/rc.d
```
1. Create the `rc.d` script:
```bash
sudo bash -c 'cat > /usr/local/etc/rc.d/gitlab_runner' << "EOF"
#!/bin/sh
# PROVIDE: gitlab_runner
# REQUIRE: DAEMON NETWORKING
# BEFORE:
# KEYWORD:
. /etc/rc.subr
name="gitlab_runner"
rcvar="gitlab_runner_enable"
load_rc_config $name
user="gitlab-runner"
user_home="/home/gitlab-runner"
command="/usr/local/bin/gitlab-ci-multi-runner run"
pidfile="/var/run/${name}.pid"
start_cmd="gitlab_runner_start"
stop_cmd="gitlab_runner_stop"
status_cmd="gitlab_runner_status"
gitlab_runner_start()
{
export USER=${user}
export HOME=${user_home}
if checkyesno ${rcvar}; then
cd ${user_home}
/usr/sbin/daemon -u ${user} -p ${pidfile} ${command} > /var/log/gitlab_runner.log 2>&1
fi
}
gitlab_runner_stop()
{
if [ -f ${pidfile} ]; then
kill `cat ${pidfile}`
fi
}
gitlab_runner_status()
{
if [ ! -f ${pidfile} ] || kill -0 `cat ${pidfile}`; then
echo "Service ${name} is not running."
else
echo "${name} appears to be running."
fi
}
run_rc_command $1
EOF
```
1. Make it executable:
```bash
sudo chmod +x /usr/local/etc/rc.d/gitlab_runner
```
1. Register the Runner (look into [runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
```bash
sudo -u gitlab-runner -H /usr/local/bin/gitlab-ci-multi-runner register
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com):
Please enter the gitlab-ci token for this runner:
Please enter the gitlab-ci description for this runner:
[name]:
Please enter the gitlab-ci tags for this runner (comma separated):
Registering runner... succeeded
Please enter the executor: virtualbox, ssh, shell, parallels, docker, docker-ssh:
shell
Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded!
```
1. Enable the `gitlab-runner` service and start it:
```bash
sudo sysrc -f /etc/rc.conf "gitlab_runner_enable=YES"
sudo service gitlab_runner start
```
If you don't want to enable the `gitlab-runner` service to start after a
reboot, use:
```bash
sudo service gitlab_runner onestart
```
......@@ -5,11 +5,11 @@ There are three ways to install it. Using Docker, download the binary manually o
use the repository for rpm/deb packages that GitLab offers. Below you can find
information on the different installation methods:
- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat (preferred)](linux-repository.md)
- [Install using GitLab's repository for Debian/Ubuntu/CentOS/RedHat](linux-repository.md) (preferred)
- [Install on GNU/Linux manually](linux-manually.md)
- [Install on macOS (preferred)](osx.md)
- [Install on Windows (preferred)](windows.md)
- [Install as a Docker Service](docker.md)
- [Install on macOS](osx.md)
- [Install on Windows](windows.md)
- [Install as a Docker service](docker.md)
- [Install in Auto-scaling mode using Docker machine](autoscaling.md)
- [Install on FreeBSD](freebsd.md)
- [Install on Kubernetes](kubernetes.md)
......
## Run gitlab-runner on a Kubernetes cluster
# Run GitLab Runner on a Kubernetes cluster
To get started with the GitLab CI Runner on Kubernetes you need to define
resources that you can then push to the cluster with kubectl.
resources that you can then push to the cluster with `kubectl`.
A recommended approach to this is to create a `ConfigMap` in Kubernetes such as
the following:
......
## Manual installation and configuration
# Manual installation and configuration on GNU/Linux
### Install
>**Note:**
Make sure that you read the [FAQ](../faq/README.md) section which describes
some of the most common problems with GitLab Runner.
If you don't want to use a [deb/rpm repository](linux-repository.md) to install
GitLab Runner, or your OS is not among the supported ones, you can install it
manually.
## Install
Simply download one of the binaries for your system:
......@@ -22,32 +30,33 @@ Optionally, if you want to use Docker, install Docker with:
curl -sSL https://get.docker.com/ | sh
```
Create a GitLab CI user (on Linux):
Create a GitLab CI user:
```
sudo useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
```
Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
```bash
sudo gitlab-ci-multi-runner register
```
Install and run as service (on Linux):
Install and run as service:
```bash
sudo gitlab-ci-multi-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
sudo gitlab-ci-multi-runner start
```
> **Notice**
>**Note**
If `gitlab-ci-multi-runner` is installed and run as service (what is described
in this page), it will run as root, but will execute jobs as user specified by
the `install` command. This means that some of the job functions like cache and
artifacts will need to execute `/usr/local/bin/gitlab-ci-multi-runner` command,
therefore the user under which jobs are run, needs to have access to the executable.
>Note that if gitlab-ci-multi-runner is installed and run as service (what is described in this page),
it will run as root, but will execute jobs as user specified by the `install` command. This means that some of the
job functions like cache and artifacts will need to execute `/usr/local/bin/gitlab-ci-multi-runner` command, therefore
the user under which jobs are run, needs to have access to the executable.
### Update
## Update
Stop the service (you need elevated command prompt as before):
......@@ -55,7 +64,7 @@ Stop the service (you need elevated command prompt as before):
sudo gitlab-ci-multi-runner stop
```
Download the binary to replace runner's executable:
Download the binary to replace Runner's executable:
```bash
sudo wget -O /usr/local/bin/gitlab-ci-multi-runner https://gitlab-ci-multi-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-ci-multi-runner-linux-386
......@@ -73,6 +82,3 @@ Start the service:
```bash
sudo gitlab-ci-multi-runner start
```
Make sure that you read the [FAQ](../faq/README.md) section which describes
some of the most common problems with GitLab Runner.
### Install using official GitLab repositories
# Install GitLab Runner using the official GitLab repositories
Currently we support Debian, Ubuntu, RHEL and CentOS.
Currently we support:
If you want to use Docker runner, install it before using the multi runner:
- Debian
- Ubuntu
- RHEL
- CentOS.
If you want to use the [Docker executor], install it before using the Runner:
```bash
curl -sSL https://get.docker.com/ | sh
```
Add GitLab's official repository via apt-get or yum:
## Add the repository
Add GitLab's official repository:
```bash
# For Debian/Ubuntu
......@@ -18,18 +25,18 @@ curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash
```
---
**APT pinning - Debian only**
>**Note:**
_Debian users should use APT pinning_
>
Since Debian Stretch, Debian maintainers added their native package
with the same name as is used by our package. And by default the official
repositories will have a priority.
with the same name as is used by our package, and by default the official
repositories will have a higher priority.
>
If you want to use our package you should manually set the source of
the package. The best would be to add the pinning configuration file.
Thanks to this every next update of the Runner's package - whether it will
be done manually or automatically - will be done using the same source:
>
```bash
cat > /etc/apt/preferences.d/pin-gitlab-runner.pref <<EOF
Explanation: Prefer GitLab provided packages over the Debian native ones
......@@ -38,7 +45,6 @@ Pin: origin packages.gitlab.com
Pin-Priority: 1001
EOF
```
---
Install `gitlab-ci-multi-runner`:
......@@ -50,7 +56,7 @@ sudo apt-get install gitlab-ci-multi-runner
sudo yum install gitlab-ci-multi-runner
```
Register the runner (Look into [runners documentation](http://doc.gitlab.com/ce/ci/runners/README.html) to learn how to obtain a token):
Register the Runner (look into [Runners documentation](https://docs.gitlab.com/ce/ci/runners/) to learn how to obtain a token):
```bash
sudo gitlab-ci-multi-runner register
......@@ -70,12 +76,12 @@ INFO[0037] Runner registered successfully. Feel free to start it, but if it's
running already the config should be automatically reloaded!
```
The runner should be started already and you are ready to build your projects!
The Runner should be started already and you are ready to build your projects!
Make sure that you read the [FAQ](../faq/README.md) section which describes
some of the most common problems with GitLab Runner.
### Update
## Update
Simply execute to install latest version:
......@@ -89,5 +95,9 @@ sudo yum update
sudo yum install gitlab-ci-multi-runner
```
### Manually download packages
You can manually download the packages from the following URL: https://packages.gitlab.com/runner/gitlab-ci-multi-runner
\ No newline at end of file
## Manually download packages
You can manually download the packages from the following URL:
<https://packages.gitlab.com/runner/gitlab-ci-multi-runner>
[docker executor]: ../executors/docker.md