From d0b50b829ce01718d32cecf7bca264469b0ff5d1 Mon Sep 17 00:00:00 2001
From: Achilleas Pipinellis <axil@gitlab.com>
Date: Fri, 6 Oct 2017 12:48:13 +0200
Subject: [PATCH] Add info on upgrading to Runner 10
Also clean up the README and move relevant info in the docs
---
README.md | 73 ++-----------------------
docs/index.md | 31 +++++++++++
docs/install/linux-repository.md | 93 ++++++++++++++++++--------------
3 files changed, 87 insertions(+), 110 deletions(-)
diff --git a/README.md b/README.md
index 502f61e4..5aafa28f 100644
--- a/README.md
+++ b/README.md
@@ -10,58 +10,8 @@ The old name of this project was GitLab CI Multi Runner but please use "GitLab R
## Runner and GitLab CE/EE compatibility
-GitLab Runner >= 9.0 requires GitLab's API v4 endpoints, which were introduced in
-GitLab CE/EE 9.0.
-
-Because of this **Runner >= 9.0 requires GitLab CE/EE >= 9.0 and will not work
-with older GitLab versions**.
-
-Old API used by Runner will be still present in GitLab >= versions until August 2017.
-Until then we will also support the v1.11.x version of Runner.
-
-> This means that if you want to have a newer version of GitLab CE/EE but for some
-reason you don't want to install newer version of Runner, 1.11.x will be still
-maintained and will be working with GitLab CE/EE until August 2017. It may not
-support some new features, but any bugs or security violations will be handled
-as for the stable version.
-
-### Compatibility chart
-
-| | 8.16.x (01.2017) | 8.17.x (02.2017) | 9.0.x (03.2017) | 9.1.x (04.2017) | 9.2.x (05.2017) | 9.3.x (06.2017) | 9.4.x (07.2017) | 9.5.x (08.2017) | 10.0.x (09.2017) |
-|:------------------:|:----------------:|:----------------:|:---------------:|:---------------:|:---------------:|:---------------:|:---------------:|:---------------:|:---------------:|
-| v1.10.x | Y, s | Y, s | Y, s | Y, **u** | Y, **u** | Y, **u** | Y, **u** | Y, **u** | **N**, **u** |
-| v1.11.x | Y | Y, s | Y, s | Y, s | Y, s | Y, s | Y, s | Y, s | **N**, **u** |
-| v9.0.x | **N** | **N** | Y, s | Y, s | Y, s | Y, **u** | Y, **u** | Y, **u** | Y, **u** |
-| v9.1.x | **N** | **N** | Y | Y, s | Y, s | Y, s | Y, **u** | Y, **u** | Y, **u** |
-| v9.2.x | **N** | **N** | Y | Y | Y, s | Y, s | Y, s | Y, **u** | Y, **u** |
-| v9.3.x | **N** | **N** | Y | Y | Y | Y, s | Y, s | Y, s | Y, **u** |
-| v9.4.x | **N** | **N** | Y | Y | Y | Y | Y, s | Y, s | Y, s |
-| v9.5.x | **N** | **N** | Y | Y | Y | Y | Y | Y, s | Y, s |
-| v10.0.x _(planned)_ | **N** | **N** | Y | Y | Y | Y | Y | Y | Y, s |
-
-**Legend**
-
-* Y - specified Runner version is/will be working with specified GitLab version
-* N - specified Runner version is/will not be working with specified GitLab version
-* s - specified Runner version is supported
-* u - specified Runner version is not supported
-
-### How to install older versions
-
-Let's assume that you want to install version 1.11.2 of Runner:
-
-1. If you're using DEB/RPM based installation:
-
- ```bash
- # for DEB based systems
- root@host:# apt-get install gitlab-runner=10.0.0
-
- # for RPM based systems
- root@host:# yum install gitlab-runner-10.0.0-1
- ```
-
-1. If you need to install Runner manually, you can look for a propper package/binary
- at https://gitlab-runner-downloads.s3.amazonaws.com/v10.0.0/index.html
+For a list of compatible versions between GitLab and GitLab Runner, consult
+the [compatibility chart](https://docs.gitlab.com/runner/#compatibility-chart).
## Release process
@@ -102,7 +52,7 @@ read the documentation online at https://docs.gitlab.com/runner/.
[Read about the features of GitLab Runner.](https://docs.gitlab.com/runner/#features)
-## Compatibility chart
+## Executors compatibility chart
[Read about what options each executor can offer.](https://docs.gitlab.com/runner/executors/#compatibility-chart)
@@ -126,27 +76,10 @@ Read the [FAQ](https://docs.gitlab.com/runner/faq/).
See [https://docs.gitlab.com/runner/#advanced-configuration](https://docs.gitlab.com/runner/#advanced-configuration).
-## Extra projects?
-
-If you want to add another project, token or image simply RE-RUN SETUP.
-*You don't have to re-run the runner. It will automatically reload configuration once it changes.*
-
## Changelog
Visit the [Changelog](CHANGELOG.md) to view recent changes.
-### Version 0.5.0
-
-Version 0.5.0 introduces many security related changes.
-One of such changes is the different location of `config.toml`.
-Previously (prior 0.5.0) config was read from current working directory.
-Currently, when `gitlab-runner` is executed by `root` or with `sudo` config is read from `/etc/gitlab-runner/config.toml`.
-If `gitlab-runner` is executed by non-root user, the config is read from `$HOME/.gitlab-runner/config.toml`.
-However, this doesn't apply to Windows where config is still read from current working directory, but this most likely will change in future.
-
-The config file is automatically migrated when GitLab Runner was installed from GitLab's repository.
-**For manual installations the config needs to be moved by hand.**
-
## The future
* Please see the [GitLab Direction page](https://about.gitlab.com/direction/).
diff --git a/docs/index.md b/docs/index.md
index 2c371f66..8016cdc4 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -45,6 +45,37 @@ installed.
- Easy installation as a service for GNU/Linux, OSX and Windows
- Embedded Prometheus metrics HTTP server
+## Compatibility chart
+
+CAUTION: **Important:**
+GitLab Runner >= 9.0 requires GitLab's API v4 endpoints, which were introduced
+in GitLab CE/EE 9.0. Because of this change, GitLab Runner >= 9.0 requires
+GitLab CE/EE >= 9.0 and will not work with older GitLab versions.
+The old API used by GitLab Runner was deprecated in August 2017 and with this
+the v1.11.x version of GitLab Runner is deprecated as well.
+
+In the following table you can see the compatibility chart between GitLab and
+GitLab Runner.
+
+| | 8.16.x (01.2017) | 8.17.x (02.2017) | 9.0.x (03.2017) | 9.1.x (04.2017) | 9.2.x (05.2017) | 9.3.x (06.2017) | 9.4.x (07.2017) | 9.5.x (08.2017) | 10.0.x (09.2017) |
+|:---------|:----------------:|:----------------:|:---------------:|:---------------:|:---------------:|:---------------:|:---------------:|:---------------:|:---------------:|
+| v1.10.x | Y, s | Y, s | Y, s | Y, **u** | Y, **u** | Y, **u** | Y, **u** | Y, **u** | **N**, **u** |
+| v1.11.x | Y | Y, s | Y, s | Y, s | Y, s | Y, s | Y, s | Y, s | **N**, **u** |
+| v9.0.x | **N** | **N** | Y, s | Y, s | Y, s | Y, **u** | Y, **u** | Y, **u** | Y, **u** |
+| v9.1.x | **N** | **N** | Y | Y, s | Y, s | Y, s | Y, **u** | Y, **u** | Y, **u** |
+| v9.2.x | **N** | **N** | Y | Y | Y, s | Y, s | Y, s | Y, **u** | Y, **u** |
+| v9.3.x | **N** | **N** | Y | Y | Y | Y, s | Y, s | Y, s | Y, **u** |
+| v9.4.x | **N** | **N** | Y | Y | Y | Y | Y, s | Y, s | Y, s |
+| v9.5.x | **N** | **N** | Y | Y | Y | Y | Y | Y, s | Y, s |
+| v10.0.x | **N** | **N** | Y | Y | Y | Y | Y | Y | Y, s |
+
+**Legend**
+
+* Y - specified Runner version is/will be working with specified GitLab version
+* N - specified Runner version is/will not be working with specified GitLab version
+* s - specified Runner version is supported
+* u - specified Runner version is not supported
+
## [Install GitLab Runner](install/index.md)
GitLab Runner can be installed and used on GNU/Linux, macOS, FreeBSD and Windows.
diff --git a/docs/install/linux-repository.md b/docs/install/linux-repository.md
index ab983e27..2a4fc613 100644
--- a/docs/install/linux-repository.md
+++ b/docs/install/linux-repository.md
@@ -1,44 +1,36 @@
# Install GitLab Runner using the official GitLab repositories
-Currently we support:
+The currently supported distributions are:
- Debian
- Ubuntu
- RHEL
- CentOS
+- Fedora (added in 10.0)
-If you want to use the [Docker executor], install it before using the Runner:
+## Prerequisites
-```bash
-curl -sSL https://get.docker.com/ | sh
-```
+If you want to use the [Docker executor], make sure to install Docker before
+using the Runner. [Read how to install Docker for your distribution](https://docs.docker.com/engine/installation/).
## Installing the Runner
+CAUTION: **Important:**
+If you are using or upgrading from a version prior to GitLab Runner 10, read how
+to [upgrade to the new version](#upgrading-to-gitlab-runner-10).
+
To install the Runner:
1. Add GitLab's official repository:
- **For GitLab Runner 10.0 and newer**
-
```bash
# For Debian/Ubuntu
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
- # For RHEL/CentOS
+ # For RHEL/CentOS/Fedora
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.rpm.sh | sudo bash
```
- **For versions older than 10.0, please use**
-
- ```bash
- # For Debian/Ubuntu
- curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | sudo bash
-
- # For RHEL/CentOS
- curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash
- ```
-
>**Note:**
_Debian users should use APT pinning_
>
@@ -60,26 +52,27 @@ To install the Runner:
EOF
```
-1. Install `gitlab-runner`:
-
- **For GitLab Runner 10.0 and newer**
+1. Install the latest version of GitLab Runner, or skip to the next step to
+ install a specific version:
```bash
# For Debian/Ubuntu
sudo apt-get install gitlab-runner
- # For RHEL/CentOS
+ # For RHEL/CentOS/Fedora
sudo yum install gitlab-runner
```
- **For versions older than 10.0, please use**
+1. To install a specific version of GitLab Runner:
```bash
- # For Debian/Ubuntu
- sudo apt-get install gitlab-ci-multi-runner
+ # for DEB based systems
+ apt-cache madison gitlab-runner
+ sudo apt-get install gitlab-runner=10.0.0
- # For RHEL/CentOS
- sudo yum install gitlab-ci-multi-runner
+ # for RPM based systems
+ yum list gitlab-runner --showduplicates | sort -r
+ sudo yum install gitlab-runner-10.0.0-1
```
1. [Register the Runner](../register/index.md)
@@ -94,33 +87,53 @@ some of the most common problems with GitLab Runner.
Simply execute to install latest version:
-**For GitLab Runner 10.0 and newer**
-
```bash
# For Debian/Ubuntu
sudo apt-get update
sudo apt-get install gitlab-runner
-# For RHEL/CentOS
+# For RHEL/CentOS/Fedora
sudo yum update
sudo yum install gitlab-runner
```
+## Manually download packages
-**For versions older than 10.0, please use**
+You can manually download the packages from the following URL:
+<https://packages.gitlab.com/runner/gitlab-runner>
+
+## Upgrading to GitLab Runner 10
+
+In GitLab Runner 10, the name of the executable was named from `gitlab-ci-multi-runner`
+to just `gitlab-runner`. With that change, GitLab Runner
+[has a new home](https://gitlab.com/gitlab-org/gitlab-runner) and the package
+repository [was renamed as well](https://packages.gitlab.com/runner/gitlab-runner).
+
+To upgrade GitLab Runner from a version older than 10.0:
+
+1. Remove the old repository:
+
+ ```
+ # For Debian/Ubuntu
+ sudo rm /etc/apt/sources.list.d/runner_gitlab-ci-multi-runner.list
+
+ # For RHEL/CentOS
+ sudo rm /etc/yum.repos.d/runner_gitlab-ci-multi-runner.repo
+ ```
+
+1. Follow the same steps when [installing the Runner](#installing-the-runner),
+ **without registering it** and using the new repository.
+
+## Old GitLab Runner URLs
+
+For versions older than 10.0, replace the repository URLs in the install section
+with the following:
```bash
# For Debian/Ubuntu
-sudo apt-get update
-sudo apt-get install gitlab-ci-multi-runner
+curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.deb.sh | sudo bash
# For RHEL/CentOS
-sudo yum update
-sudo yum install gitlab-ci-multi-runner
+curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-ci-multi-runner/script.rpm.sh | sudo bash
```
-## Manually download packages
-
-You can manually download the packages from the following URL:
-<https://packages.gitlab.com/runner/gitlab-runner>
-
[docker executor]: ../executors/docker.md
--
GitLab