# GitLab CI

Run GitLab CI jobs on Groundbox: a fresh VM for each job, billed per second at the same prices as GitHub Actions jobs. It works with gitlab.com and with self-managed GitLab. You change one line in `.gitlab-ci.yml`.

## Connect GitLab

The quickest way: Groundbox creates the runner on GitLab for you. You need Maintainer on the project, or Owner on the group.

1. In the dashboard, open **Repos and runners > GitLab** and click **Connect GitLab**. GitLab asks you to let Groundbox read your projects and groups and create and manage runners (`read_api`, `create_runner`, `manage_runner`). Only a team owner or admin can connect.
2. Back in the dashboard, pick a size (`groundbox`, the auto size, unless you choose another), then click **Add runner** next to a project or group. A group runner serves every project in the group.
3. Groundbox creates a runner there with that size as its only tag, for tagged jobs only, and keeps its token. Add another runner for each other size you want.

Removing a runner in the dashboard deletes it on GitLab too. **Disconnect** deletes every runner Groundbox created and revokes its access to your GitLab account. Connect GitLab is for gitlab.com; for self-managed GitLab, paste a runner token.

## Or paste a runner token

1. In GitLab, open the project (or group) and go to **Settings > CI/CD > Runners > New project runner**.
2. Add the tag of the size you want, for example `groundbox-4vcpu`, and create the runner. Leave "Run untagged jobs" off.
3. Copy the runner authentication token (it starts with `glrt-`). You do not need to run anything GitLab shows next.
4. In the dashboard, open **Repos and runners > GitLab > Paste a runner token**, paste the token and pick the same size. For self-managed GitLab, also enter its address.

Disconnecting a pasted runner stops Groundbox taking its jobs and forgets its token; delete the runner in GitLab yourself.

## Use it

```
test:
  image: node:22        # optional: without it the job runs on Ubuntu 24.04
  tags: [groundbox-4vcpu]
  script:
    - npm ci
    - npm test
```

A job with that tag runs on Groundbox, whichever way its runner was connected. Connect one GitLab runner per size you use: `groundbox-2vcpu`, `groundbox-4vcpu`, `groundbox-8vcpu`, `groundbox-16vcpu`, or `groundbox` for the auto size, which picks a size per job from its earlier runs.

## Images and services

A job with `image:` or `services:` runs the way GitLab's Docker executor runs it, in containers on the job's own VM. A job without an image runs directly on Ubuntu 24.04 with the same tools as our GitHub Actions runners.

## Logs, artifacts and cancel

The job's log, artifacts, status and cancel button are GitLab's own, as with any runner. The dashboard lists each job with its time and cost and links to it in GitLab.

## Limits

- `cache:` does not carry over between jobs yet: each job starts on a clean VM.
- Self-managed GitLab must be reachable over HTTPS from the internet.
- Live logs, the terminal on a job and test insights are for GitHub Actions jobs only for now.

## Compute minutes

A Groundbox runner is a project or group runner to GitLab, so its jobs do not use GitLab compute minutes. Compare a month on GitLab.com's hosted runners with the [GitLab compute minutes calculator](https://groundbox.dev/gitlab-compute-minutes), or read the [GitLab runner guide](https://groundbox.dev/gitlab-runner) for executors, registering and what self-hosting costs.
