How to Make a Runner? | GitLab CI/CD Setup

For the full breakdown, see our best Custom Aisle Runners For Weddings guide.

GitLab Runner is an application that works with GitLab CI/CD to execute pipeline jobs. To build, test, or deploy code automatically, creating a runner is the first step. This guide walks through the full process, from project setup to a running pipeline.

What Exactly Is a GitLab Runner?

GitLab Runner is a lightweight agent that picks up jobs from your pipeline and executes them — compiling code, running tests, or deploying. Runners can live on the same machine as your GitLab instance or on separate hardware. The runner communicates with GitLab, asks for jobs, and reports results back.

Creating a Runner: Step-by-Step

1. Create a Blank Project

Sign in and create a new blank project — a workspace to attach the runner and test the pipeline.

2. Add a Pipeline File

Create .gitlab-ci.yml in the project root. A minimal example:

stages:
 - test

job-test:
 stage: test
 script:
 - echo "Hello, Runner!"

3. Open Runners Settings

Navigate to Settings > CI/CD > Runners.

4. Create the Project Runner

Select Create project runner, configure tags (which route jobs), and check Run untagged if jobs lack tags. Select Create runner to generate your registration token.

Registering Your Runner

The Registration Command

Install gitlab-runner, then run:

sudo gitlab-runner register \
 --url https://gitlab.com \
 --token YOUR_PROJECT_TOKEN

Choose an Executor

Enter shell to run directly on the host — the simplest option. Others (Docker, Kubernetes, SSH) add isolation but more setup complexity.

Start the Runner

gitlab-runner run

Job Tagging and Runner Behavior

Advanced configuration lives in config.toml, controlling concurrency, executor behavior, and custom settings.

Common Pitfalls

Confusing runner creation with pipeline creation. Both are required — the pipeline file defines jobs, the runner executes them. You need .gitlab-ci.yml before the runner has work.

Missing tags. If jobs specify tags and the runner doesn’t match, jobs stay pending. Remove tags or add matching ones.

Registration platform differences. Steps vary by OS and installation method — follow GitLab’s on-screen instructions.