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
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets 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.
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
7

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

### Requirements

13
### Omnibus packages and other platforms
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets 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/).
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
18

19
### Supported platforms
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets 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/).
33

34
### Install dependencies
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets 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
41

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
```
46

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

49
```bash
50
brew install icu4c
51
```
52 53 54 55

Install Ruby from source:

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

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
61 62 63 64
./configure --disable-install-rdoc
make
sudo make install
```
65

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

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:
83

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

```
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
104
```
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
105

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

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

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

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

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)
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets 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)
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
154

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
158
sudo chmod +x /etc/init.d/gitlab-ci-runner
159
sudo update-rc.d gitlab-ci-runner defaults 21
Dmitriy Zaporozhets's avatar
Dmitriy Zaporozhets committed
160
```
161

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

169 170
### Run

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

173 174
```bash
sudo service gitlab-ci-runner start
175 176
```

177
OR
178

179
Manually:
180

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

196
In order to update the runner to a new version just go to runner directory and do next:
197

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
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).