runner.md 8.38 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
# Using GitLab Runner with GDK

Most features of [GitLab CI](http://docs.gitlab.com/ce/ci/) need a
[Runner](http://docs.gitlab.com/ce/ci/runners/README.html) to be registered with
the GitLab installation. This HOWTO will take you through the necessary steps to
do so when GitLab is running under GDK.

## Set up GitLab

Start by [preparing your computer](../prepare.md) and
[setting up GDK](../set-up-gdk.md).

In some configurations, GitLab Runner needs access to GitLab from inside a
Docker container, or even another machine, which isn't supported in the default
Evan Read's avatar
Evan Read committed
15 16 17 18 19 20 21
configuration.

### Simple configuration

If you intend to just use the "shell" executor (fine for very
simple jobs), you can use GDK with its default settings and skip the Advanced
configuration below. If GDK is already running, you'll need to restart it after making
22 23
these changes.

Evan Read's avatar
Evan Read committed
24 25 26 27 28 29 30 31
With GDK running:

1. Navigate to `http://localhost:3000/admin/runners` (log in as root)
1. Make note of the `Registration token`.

### Advanced configuration

Ensure you have Docker installed, then set up GitLab to bind to all
32 33
IPs on your machine by following [these instructions](local_network.md).
Without this step, builds will fail with a 'connection refused' error.
34

35 36 37
The `gitlab/config/gitlab.yml` configuration file also needs tweaking in the following sections:

 - GitLab host:
38 39 40 41 42 43 44 45 46 47 48 49

```yaml
production: &base
  #
  # 1. GitLab app settings
  # ==========================

  ## GitLab settings
  gitlab:
    ## Web server settings (note: host is the FQDN, do not include http://)
    host: localhost
```
50

51 52 53 54 55 56 57 58 59 60 61 62
 - Webpack dev server host:

```yaml
  ## Webpack settings
  webpack:
    dev_server:
      enabled: true
      host: 127.0.0.1
      port: 3808
```

The `host` parameter needs to be changed from `localhost`/ `127.0.0.1` to an IP address that
63 64 65 66 67 68
*actually exists on the computer*. `0.0.0.0` is not valid - run `ipconfig`
(Windows), `ifconfig` (Mac, BSD) or `ip addr show` (Linux) to get a list of IPs.
The right one to use depends on your network, and may change from time to time,
but an address like `10.x.x.x`, `172.16.x.x` or `192.168.x.x` is normally the
right one.

Stan Hu's avatar
Stan Hu committed
69 70
NOTE: If you want to use a Docker executor, see [the section
below](#docker-executor).
71

72
Now run GDK: `gdk start`. Navigate to `http://<ip>:3000/gitlab-org/gitlab-test`.
73 74 75 76 77 78 79 80
If the URL doesn't work, repeat the last step and pick a different IP.

Once there, ensure that the HTTP clone URL is `http://<ip>:3000/gitlab-org/gitlab-test.git`.
If it points to `localhost` instead, `gitlab/config/gitlab.yml` is incorrect.

Finally, navigate to `http://<ip>:3000/admin/runners` (log in as root) and make
a note of the `Registration token`.

81
## Download GitLab Runner
82

83 84
### Simple configuration

85 86
Unless you want to make changes to the Runner, it's easiest to install a binary
package. Follow the
87
[installation instructions](https://docs.gitlab.com/runner/install/)
88
for your operating system
89 90 91
([Linux](https://docs.gitlab.com/runner/install/linux-repository.html),
[OSX](https://docs.gitlab.com/runner/install/osx.html),
[Windows](https://docs.gitlab.com/runner/install/windows.html)).
92 93 94

To build from source, you'll need to set up a development environment manually -
GDK doesn't manage it for you. The official GitLab Runner repository is
95
[here](https://gitlab.com/gitlab-org/gitlab-runner); just follow
96
[the development instructions](https://docs.gitlab.com/runner/development/).
97

98
All the methods should (eventually) create a `gitlab-runner` binary.
99

100 101 102 103
### Advanced configuration

If you followed the advanced configuration and want to install the runner as a docker service, follow the steps described in <https://docs.gitlab.com/runner/install/docker.html#docker-image-installation>.

104 105
## Setting up the Runner

106 107
### Simple configuration

108
Run `gitlab-runner register --run-untagged --config <path-to-gdk>/gitlab-runner-config.toml`
109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
(as your normal user), and follow the prompts. Use:

- **coordinator URL**

  Use either:

  - `http://localhost:3000/`
  - `http://<custom_IP_address>:3000/`, if you customized your IP address using
    [Advanced Configuration](#advanced-configuration).
- **gitlab-ci token**

  `Registration token` (copied from `admin/runners`)
- **gitlab-ci description** (optional)

  A description of the Runner. Defaults to the hostname of the machine.
- **gitlab-ci tags** (optional)

  Comma-separated tags. Jobs can be set up to use only Runners with specific tags.

128 129 130 131 132 133 134 135 136 137 138
The Runner will write its configuration file to `gitlab-runner-config.toml`,
which is in GDK's `.gitignore` file.

If Docker is installed and you followed the special setup instructions above,
choose `docker` as the executor. Otherwise, choose `shell` - but remember that
builds will then be run directly on the host computer! Don't use random
`.gitlab-ci.yml` files from the Internet unless you understand them fully, it
could be a security risk.

You can run the `register` command multiple times to set up additional Runners -
fuller documentation on the different types of executor and their requirements
139
can be found [here](https://docs.gitlab.com/runner/executors/).
140 141 142
Each `register` invocation adds a section to the configuration file, so make
sure you're referencing the same one each time.

Alex Ives's avatar
Alex Ives committed
143 144 145 146 147
Finally, rebuild your `Procfile` with `rm Procfile; make Procfile` or un-comment
the line that starts with `runner:`. This will allow you to manage it along with
your other GDK processes.

Alternately, run `gitlab-runner --log-level debug run --config <path-to-gdk>/gitlab-runner-config.toml`
148 149 150 151 152 153
to get a long-lived Runner process, using the configuration you created in the
last step. It will stay in the foreground, outputting logs as it executes
builds, so run it in its own terminal session.

The Runners pane in the administration panel will now list the Runners. Create a
project in the GitLab web interface and add a
154
[.gitlab-ci.yml](https://docs.gitlab.com/ce/ci/examples/) file,
155 156
or clone an [example project](https://gitlab.com/groups/gitlab-examples), and
watch as the Runner processes the builds just as it would on a "real" install!
157 158 159 160 161

### Advanced configuration

Register your docker-based runner by following the steps described in <https://docs.gitlab.com/runner/register/index.html#docker>.

Stan Hu's avatar
Stan Hu committed
162 163
### Docker executor

164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188
#### Docker for Mac

Docker for Mac [has some networking
limitations](https://docs.docker.com/docker-for-mac/networking/), but
you can still get CI runners working with a Docker executor by using a
hostname trick. Within a container, Docker maps the
`host.docker.internal` hostname to the host IP address
(e.g. 192.168.65.2). On the host network, you can map this hostname to
the local IP address (e.g. 127.0.0.1) and use this hostname in three
different configuration files:

1. In `config/gitlab.yml`, set the `host` parameter to `host.docker.internal`.
1. In `/etc/hosts`, add an entry:

   ```
   127.0.0.1   host.docker.internal
   ```

1. In the GitLab runner config (e.g. `~/.gitlab-runner/config.toml`), set the coordinator
   URL with this hostname:

   ```toml
    url = "http://host.docker.internal:3001/"
   ```

Stan Hu's avatar
Stan Hu committed
189 190 191 192 193 194 195 196 197 198 199
Note that all three settings must be set to ensure a number of items
work with the runner:

1. Registering the runner
1. Polling for jobs on the host network
1. Making API requests (e.g. sending artifacts) inside the container during a CI job.
1. Cloning the repository ([`CI_REPOSITORY_URL`](https://docs.gitlab.com/ee/ci/variables/predefined_variables.html))

The `/etc/hosts` parameter is needed to make the first two items work,
since this maps `host.docker.internal` to `localhost`. The `config.toml`
changes allow the third item to work. The `gitlab.yml` changes are used
200
for the fourth item.
Stan Hu's avatar
Stan Hu committed
201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233

#### Using an internal, dummy interface

The trick described above is a bit of a hack and only works for Docker
for Mac, but the "proper" way to support a Docker executor is to use an
internal, dummy interface that can be used by both the host and the
container.  Here's how:

1. Create an internal interface. On macOS, this will add an alias IP
   172.16.123.1 to the loopback adapter:

    ```sh
    sudo ifconfig lo0 alias 172.16.123.1
    ```

    On Linux, you can create a dummy interface:

    ```sh
    sudo ip link add dummy0 type dummy
    ifconfig dummy0 172.16.123.1
    ```

1. In `config/gitlab.yml`, set the `host` parameter to `172.16.123.1`.

1. In the GitLab runner config (e.g. `~/.gitlab-runner/config.toml`), set the coordinator
   URL with this hostname:

   ```toml
    url = "http://172.16.123.1:3001/"
   ```

Note that for this to work across reboots, the aliased IP in step 1 needs to be run
at startup.