Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 36 ยท Runners and Jobs

Runners: Where Your Jobs Run

Understand GitLab Runner: what it is, instance, group and project runners, hosted versus self-managed, tags, how a job finds a runner and common stuck-job fixes.

GitLab itself never executes your pipeline commands. It stores the configuration, creates the jobs and keeps the queue. The work is done by runners: separate programs, usually on separate machines, that ask GitLab for jobs, run the scripts and send back logs and results. Understanding runners explains most "why is my job stuck?" and "why does it work on my laptop?" problems.

How a runner gets work

A runner is a small application called GitLab Runner, written in Go, that runs on Linux, macOS, Windows, in containers or on Kubernetes. It works by polling: every few seconds it asks the GitLab server, "any jobs for me?" This is why runners can sit behind firewalls and NAT without any inbound connections: they only make outgoing HTTPS requests.

sequenceDiagram
  participant G as GitLab server
  participant R as Runner
  participant E as Executor (shell or Docker)
  R->>G: Any job for me?
  G-->>R: Job 1234 with script, variables, token
  R->>E: Prepare environment, clone repository
  E-->>R: Output of each command
  R->>G: Stream log, upload artifacts, report status

The runner pulls work; GitLab never pushes into your network.

When it receives a job, the runner prepares an environment using its executor (the next lessons cover registering and executors), clones the repository, runs before_script, script and after_script, uploads artifacts and cache, and reports the final status.

Runner scopes

Who may use a runner depends on where it is registered:

  • Instance runners (shared): available to every project on the GitLab instance. On GitLab.com these are the hosted runners GitLab operates for you, billed in compute minutes against your plan's quota.
  • Group runners: available to all projects in a group and its subgroups. A good fit for a team that wants its own machines without registering one per project.
  • Project runners: dedicated to one project (or a few), for special hardware or tight security.

Where you can see them: in a project, Settings, then CI/CD, then Runners, which lists the runners available and lets you toggle shared ones. Administrators manage instance runners in the Admin area.

Hosted versus self-managed

On GitLab.com you can start with hosted runners: no installation, clean virtual machines, several sizes and operating systems (Linux, and others depending on plan). The trade-offs are the compute-minute quota, limited customization, and the fact that your code builds on someone else's infrastructure.

Self-managed runners run on machines you control (an old server, a cloud VM, a Kubernetes cluster). Benefits: unlimited minutes (you pay for the hardware), special tools or GPUs, access to private networks and caches, and data staying on your side. The cost is maintenance: updates, security and capacity are yours. Many organizations use hosted runners for general work and self-managed ones for deployments inside their network.

Tags: matching jobs to runners

Tags are labels that connect jobs to runners. A runner registered with tags docker, linux only takes jobs that list tags it has; a job asking for a tag that no runner has stays pending forever.

YAML
build-image:
  tags:
    - docker
    - linux
  script: docker build -t app .

gpu-training:
  tags:
    - gpu
  script: python train.py

A runner can also be set to run untagged jobs (jobs with no tags). A job runs on a runner only if the runner has all the job's tags. The stand-in below implements this matching, with a few invented runners, so you can see why a job is picked or why it waits.

Python Stand-in: which runner will take this job?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Notice windows-pkg: with no Windows runner, it would sit pending until someone registers one with that tag.

Capacity and concurrency

A runner can run several jobs at once up to its concurrent limit (set in its configuration file, covered next). If more jobs wait than the runners can handle, jobs queue as pending. Plan capacity from your busiest period: a pipeline with 20 parallel test jobs needs runners able to run 20 at a time to finish quickly. Autoscaling executors create and destroy machines on demand so you pay only for what is used.

Runner security basics

  • Treat a runner as a machine that executes whatever is in the repository's .gitlab-ci.yml. Anyone who can push CI code to a project using your runner can run commands on it.
  • Do not register powerful, shared runners with access to production secrets for open or untrusted projects. Keep deployment runners on protected branches and tags only (a runner can be restricted to protected refs).
  • Prefer Docker or Kubernetes executors, which isolate jobs better than the plain shell executor.
  • Keep runners updated; the runner version should match your GitLab version's minor release where possible.
  • Rotate or delete runners that are no longer used, and give them clear descriptions.

Debugging a stuck job

When a job stays pending or stuck:

  1. Open the job. GitLab often says "This job is stuck because you don't have any active runners that can run this job" and may list the tags it needs.
  2. Compare the job's tags with the runners listed in project Settings, CI/CD, Runners.
  3. Check that the runner is online (a green dot), not paused, and that "run untagged jobs" is enabled if the job has no tags.
  4. Check whether the runner is limited to protected branches while your branch is not protected.
  5. On GitLab.com, check that you still have compute minutes remaining.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a runner receive jobs?

    Runners poll GitLab over outgoing HTTPS, so no inbound firewall holes are needed.
  2. 2. Which runner type is available to every project in a group?

    Group runners serve all projects in a group and its subgroups.
  3. 3. A job has tags: [gpu], but no registered runner has the gpu tag. What happens?

    A job only runs on a runner that has all its tags; without one it waits as stuck.
  4. 4. Why be careful about who can edit .gitlab-ci.yml on a project using your self-managed runner?

    Whoever controls the pipeline file controls the commands executed on your runner.

Summary

  • Runners are separate agents that poll GitLab, execute job scripts and report back.
  • Instance, group and project runners differ in who can use them; GitLab.com offers hosted runners billed in compute minutes.
  • Self-managed runners give control and unlimited minutes in exchange for maintenance.
  • Tags connect jobs to runners; a job needs a runner that has all its tags.
  • Treat runners as sensitive machines and use isolation and protected refs.

Next: Installing and Registering Runners