README.md 5.95 KB
Newer Older
Valeriy's avatar
Valeriy committed
1
## GitLab Runner PROJECT IS DEPRECATED NOW, PLEASE USE NEW [GitLab Runner written in Go (previously named GitLab CI Multi Runner)](https://gitlab.com/gitlab-org/gitlab-ci-multi-runner) INSTEAD
Valeriy's avatar
Valeriy committed
2

3
## GitLab Runner
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
4

5 6
This is GitLab Runner repository, this application run tests and sends the results to GitLab CI.
[GitLab CI](https://about.gitlab.com/gitlab-ci) is the open-source continuous integration server that coordinates the testing.
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
7

Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
8
[![build status](https://ci.gitlab.org/projects/8/status.png?ref=master)](https://ci.gitlab.org/projects/8?ref=master)
Sid Sijbrandij's avatar
Sid Sijbrandij committed
9
[![Code Climate](https://codeclimate.com/github/gitlabhq/gitlab-ci-runner.png)](https://codeclimate.com/github/gitlabhq/gitlab-ci-runner)
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
10 11 12

### Requirements

13
### Omnibus packages and other platforms
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
14

15 16 17
The recommended way to install this runner are the Omnibus packages.
GitLab runners are also available for all kinds of other platforms such as Windows and OSX.
For more information about both please see the runner section of the [GitLab CI page on the website](https://about.gitlab.com/gitlab-ci/).
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
18

19
### Supported platforms
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
20

21 22 23 24 25 26 27 28
This projects officially support these Linux distributions:

- Ubuntu
- Debian
- CentOS
- Red Hat Enterprise Linux
- Scientific Linux
- Oracle Linux
29

30
Mac OSX and other POSIX operating systems are not supported but will work with adaptations.
31
Under Windows the runner will only work under POSIX compliant environments like Cygwin.
32
Also see the alternative Runners for Windows, Scala/Java and Node please see the runner section of the [GitLab CI page on the website](https://about.gitlab.com/gitlab-ci/).
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
33

Marin Jankovski's avatar
Marin Jankovski committed
34
### Install dependencies
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
35

36 37
The easiest and recommended way to install the runner is with the [GitLab Runner Omnibus package](https://gitlab.com/gitlab-org/omnibus-gitlab-runner/blob/master/doc/install/README.md).

38 39 40
Install operating system dependent dependencies:

a) Linux
Raymii's avatar
Raymii committed
41

Marin Jankovski's avatar
Marin Jankovski committed
42 43 44 45
```bash
sudo apt-get update -y
sudo apt-get install -y wget curl gcc libxml2-dev libxslt-dev libcurl4-openssl-dev libreadline6-dev libc6-dev libssl-dev make build-essential zlib1g-dev openssh-server git-core libyaml-dev postfix libpq-dev libicu-dev
```
Raymii's avatar
Raymii committed
46

47 48
b) MacOSX (make sure you have [homebrew](http://brew.sh/) installed)

Marin Jankovski's avatar
Marin Jankovski committed
49
```bash
50
brew install icu4c
Marin Jankovski's avatar
Marin Jankovski committed
51
```
52 53 54 55

Install Ruby from source:

a) Linux
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
56

Marin Jankovski's avatar
Marin Jankovski committed
57 58
```bash
mkdir /tmp/ruby && cd /tmp/ruby
Valery Sizov's avatar
Valery Sizov committed
59 60
curl --progress http://cache.ruby-lang.org/pub/ruby/2.1/ruby-2.1.5.tar.gz | tar xz
cd ruby-2.1.5
Marin Jankovski's avatar
Marin Jankovski committed
61 62 63 64
./configure --disable-install-rdoc
make
sudo make install
```
Raymii's avatar
Raymii committed
65

66
b) Mac OS X (make sure you have the Xcode command line tools installed), UNTESTED
67

Marin Jankovski's avatar
Marin Jankovski committed
68 69 70 71 72 73 74 75 76 77 78
```bash
brew update
brew install rbenv
brew install ruby-build
brew install openssl
CC=gcc-4.7 RUBY_CONFIGURE_OPTS="--with-openssl-dir=`brew --prefix openssl` --with-readline-dir=`brew --prefix readline` --with-gcc=gcc-4.7 --enable-shared" rbenv install 2.0.0-p353
echo 'if which rbenv > /dev/null; then eval "$(rbenv init -)"; fi' >> ~/.profile
rbenv global 2.0.0-p353
```

### Setup runners
79

80 81 82
#### Create the runner user

Ubuntu:
Raymii's avatar
Raymii committed
83

Marin Jankovski's avatar
Marin Jankovski committed
84 85
```
sudo gem install bundler
86
sudo adduser --disabled-login --gecos 'GitLab Runner' gitlab_ci_runner
87 88 89 90 91 92 93 94 95 96 97 98
```

Centos:

```
sudo groupadd gitlab_ci_runner
sudo useradd -g gitlab_ci_runner gitlab_ci_runner
```

#### Clone the gitlab-ci-runner repository

```
Marin Jankovski's avatar
Marin Jankovski committed
99 100 101 102
sudo su gitlab_ci_runner
cd ~/
git clone https://gitlab.com/gitlab-org/gitlab-ci-runner.git
cd gitlab-ci-runner
103
git checkout VERSION_YOU_NEED # Ex. v5.0.0
Marin Jankovski's avatar
Marin Jankovski committed
104
```
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
105

Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
106
Install the gems for the runner:
107

Marin Jankovski's avatar
Marin Jankovski committed
108
```
109
bundle install --deployment
Marin Jankovski's avatar
Marin Jankovski committed
110
```
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
111

112
Setup the runner interactively:
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
113

Marin Jankovski's avatar
Marin Jankovski committed
114 115 116 117 118
```
bundle exec ./bin/setup
```

OR
Sytse Sijbrandij's avatar
Sytse Sijbrandij committed
119

120
Setup the runner non-interactively:
121

Marin Jankovski's avatar
Marin Jankovski committed
122 123 124
```
CI_SERVER_URL=https://ci.example.com REGISTRATION_TOKEN=replaceme bundle exec ./bin/setup
```
125

126 127
The registration token can be found at: <http://gitlab-ci-domain.com/admin/runners>, accessible through Header > Runners.

128 129 130 131 132 133 134
By default the configuration file for your new runner gets written in the directory where the gitlab-ci-runner source code was installed, e.g. in `/home/gitlab_ci_runner/gitlab-ci-runner/config.yml`.
You can tell `bin/setup` to use a different directory with the `-C` switch.

```
bin/setup -C /my/runner/working/directory
```

135 136
You can also specify RUNNER_DESCRIPTION and RUNNER_TAG_LIST during setup.

Valeriy's avatar
Valeriy committed
137 138 139 140 141 142 143 144
To unlink the runner from the coordinator you can run following command:

```
bin/unlink
```

It will remove the runner's information from the coordinator and remove the given token from the current runner

145
#### Create an Upstart job (Ubuntu, Centos 6)
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
146

147 148
```
exit;
149
sudo cp /home/gitlab_ci_runner/gitlab-ci-runner/lib/support/upstart/gitlab-ci-runner.conf /etc/init/
150 151 152 153
```


#### Set up an init.d script (other distributions)
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
154

Marin Jankovski's avatar
Marin Jankovski committed
155 156
```
exit;
157
sudo cp /home/gitlab_ci_runner/gitlab-ci-runner/lib/support/init.d/gitlab_ci_runner /etc/init.d/gitlab-ci-runner
Marin Jankovski's avatar
Marin Jankovski committed
158
sudo chmod +x /etc/init.d/gitlab-ci-runner
Wachiwi's avatar
Wachiwi committed
159
sudo update-rc.d gitlab-ci-runner defaults 21
Dmytro Zaporozhets (DZ)'s avatar
Dmytro Zaporozhets (DZ) committed
160
```
161

Wachiwi's avatar
Wachiwi committed
162 163 164 165 166 167
### Runners default file

```
cd /home/gitlab_ci_runner/gitlab-ci-runner
sudo cp ./lib/support/init.d/gitlab_ci_runner.default.example /etc/default/gitlab_ci_runner
```
168

Marin Jankovski's avatar
Marin Jankovski committed
169 170
### Run

171
Using the system service with Upstart/init.d script:
172

Marin Jankovski's avatar
Marin Jankovski committed
173 174
```bash
sudo service gitlab-ci-runner start
175 176
```

Marin Jankovski's avatar
Marin Jankovski committed
177
OR
178

Marin Jankovski's avatar
Marin Jankovski committed
179
Manually:
180

Marin Jankovski's avatar
Marin Jankovski committed
181 182 183 184
```bash
sudo su gitlab_ci_runner
cd /home/gitlab_ci_runner/gitlab-ci-runner
bundle exec ./bin/runner
185 186
```

187 188 189 190 191 192 193
If you are using a custom working directory you can tell the runner about it with the `-C` switch.
The default working directory is the directory where the gitlab-ci-runner source code was installed, e.g. `/home/gitlab_ci_runner/gitlab-ci-runner`.

```
bundle exec bin/runner -C /my/runner/working/directory
```

194 195
### Update

Wachiwi's avatar
Wachiwi committed
196
In order to update the runner to a new version just go to runner directory and do next:
197

Marin Jankovski's avatar
Marin Jankovski committed
198 199 200 201
```bash
sudo su gitlab_ci_runner
cd ~/gitlab-ci-runner
git fetch
202
git checkout VERSION_YOU_NEED # Ex. v5.0.0
Marin Jankovski's avatar
Marin Jankovski committed
203 204
bundle
```
205 206

And restart runner
207 208 209

## Easily add Runners to existing GitLab CI

210
See [omnibus gitlab runner](https://gitlab.com/gitlab-org/omnibus-gitlab-runner/blob/master/doc/install/README.md).
211 212 213 214

## Development

To work on the GitLab runner we recommend you install the [GitLab Development Kit](https://gitlab.com/gitlab-org/gitlab-development-kit).