GitLab Runner

What is GitLab Runner?

GitLab Runner is the agent that picks up and executes jobs defined in a project's .gitlab-ci.yml. It pairs with the GitLab service: GitLab schedules pipelines, the runner actually executes them.

Start GitLab Runner

Laradock CLI

./laradock start gitlab-runner

Docker Compose

docker compose up -d gitlab-runner

Stop GitLab Runner

Laradock CLI

./laradock stop gitlab-runner

Docker Compose

docker compose stop gitlab-runner

Configuration

All settings live in gitlab-runner/defaults.env and can be overridden by adding the same line to your own .env (your .env always wins):

Variable	Default	What it does
GITLAB_CI_SERVER_URL	http://localhost:8989	URL of the GitLab instance the runner registers against.
GITLAB_RUNNER_REGISTRATION_TOKEN	<my-registration-token>	Token from your GitLab project used to register the runner.
GITLAB_REGISTER_NON_INTERACTIVE	true	Runs gitlab-runner register without prompting when set.

By default gitlab-runner/compose.yml runs the runner with RUNNER_EXECUTOR=shell and mounts /var/run/docker.sock, so you can switch to a Docker executor instead (see below). Its config and registration state persist under DATA_PATH_HOST/gitlab/runner (mounted to /etc/gitlab-runner in the container).

Register the runner against GitLab

1. In your GitLab project, go to Settings → CI/CD → Runners and copy the registration token.
2. Set these in .env (use the container name, not localhost, since the runner talks to GitLab over the Docker network):

   GITLAB_CI_SERVER_URL=http://gitlab
   GITLAB_RUNNER_REGISTRATION_TOKEN=<value-from-step-1>

3. To use the Docker executor instead of the default shell executor, add this to gitlab-runner/compose.yml:

   gitlab-runner:
     environment: # used during `gitlab-runner register`
       - RUNNER_EXECUTOR=docker # change from shell (default)
       - DOCKER_IMAGE=alpine
       - DOCKER_NETWORK_MODE=laradock_backend
     networks:
       - backend # connect to the network where gitlab runs

4. Start the runner:

Laradock CLI

./laradock start gitlab-runner

Docker Compose

docker compose up -d gitlab-runner

5. Register it:

Laradock CLI

./laradock enter gitlab-runner
gitlab-runner register

Docker Compose

docker compose exec gitlab-runner bash
gitlab-runner register

With GITLAB_REGISTER_NON_INTERACTIVE=true (the default), register picks up CI_SERVER_URL and REGISTRATION_TOKEN from the environment automatically and doesn't prompt you for them.

6. Add a .gitlab-ci.yml to your project, push, and confirm the pipeline runs:

   before_script:
     - echo Hello!
   
   job1:
     scripts:
       - echo job1

Check runner status and logs

Laradock CLI

./laradock logs gitlab-runner

Docker Compose

docker compose logs --tail=100 gitlab-runner

To list every runner currently registered against this container (useful after re-registering or when you're not sure whether registration actually took):

Laradock CLI

./laradock enter gitlab-runner
gitlab-runner list

Docker Compose

docker compose exec gitlab-runner bash
gitlab-runner list

Unregister a runner

Do this before re-registering with different settings (a new executor, a different GitLab instance), stale registrations otherwise pile up in config.toml:

Laradock CLI

./laradock enter gitlab-runner
gitlab-runner unregister --all-runners

Docker Compose

docker compose exec gitlab-runner bash
gitlab-runner unregister --all-runners

Start completely fresh (wipe registration)

Registration state and config.toml live under DATA_PATH_HOST/gitlab/runner on your host. To throw it away and register from a clean state:

Laradock CLI

./laradock stop gitlab-runner
./laradock remove gitlab-runner
rm -rf "${DATA_PATH_HOST:-~/.laradock/data}/gitlab/runner"
./laradock start gitlab-runner

Docker Compose

docker compose stop gitlab-runner
docker compose rm -sf gitlab-runner
rm -rf "${DATA_PATH_HOST:-~/.laradock/data}/gitlab/runner"
docker compose up -d gitlab-runner

You'll need to run Register the runner against GitLab again afterward, the registration token from GitLab is still valid, only this container's local state was wiped.

Common issues

• Runner registers but jobs never pick up. Confirm GITLAB_CI_SERVER_URL points to a URL the runner container can actually reach, http://gitlab (container name), not http://localhost.
• REGISTRATION_TOKEN rejected. Tokens are per-project (or per-group/instance depending on your GitLab setup) and can be regenerated in GitLab's Settings → CI/CD → Runners, grab a fresh one if registration fails.
• Docker-executor jobs can't reach other Laradock services. Make sure DOCKER_NETWORK_MODE matches your actual Compose project's network name (laradock_backend by default, but it's prefixed by COMPOSE_PROJECT_NAME).
• Re-registering after changing executors. Changing RUNNER_EXECUTOR after the runner is already registered doesn't retroactively apply, unregister and register again, or start completely fresh.

---

Need the GitLab server this runner connects to? See GitLab. New to Laradock? Start at Getting Started.