GitLab Runner Architecture, Registration, Runner Managers, Job Execution, and Lifecycle: Configuration, Design Choices, and Tradeoffs

1. GitLab-hosted versus self-managed runners

Use hosted runners when standard isolated compute meets the requirement and the organization wants low operational overhead. Use self-managed runners when workloads require controlled networks, special hardware, custom toolchains, data locality, or organizational policy—and budget for the resulting security/maintenance responsibility.

2. Project, group, and instance scope should follow the smallest legitimate audience

Escalating scope should be treated like escalating authorization. Before promoting a runner from project to group/instance use, review every host credential, network route, cache, executor setting, privileged capability, image policy, and cleanup assumption.

3. Tags form an AND expression, not a preference list

If a job requests multiple tags, an eligible runner must have every requested tag. This supports capability routing such as [linux, amd64, signed-build], but tags are only selectors. A tag named secure does not make the runner secure.

signed_build:
  tags:
    - linux
    - amd64
    - signed-build
  script:
    - ./build-and-sign-synthetic.sh

Keep tags stable, documented, and tied to concrete properties. Avoid personal names, ambiguous environment labels, or one-off tags that turn scheduling into tribal knowledge.

4. run_untagged and protected access control different populations

Run untagged determines whether jobs with no tag requirements may use the runner. Protected runner constrains eligible refs according to protected-ref rules. For sensitive deployment/signing runners, it is common to require both explicit tags and protected refs, plus isolated execution and narrow credentials.

Neither control alone protects a persistent Shell runner from trusted-but-buggy code. Routing policy decides who may arrive; executor/host isolation decides what the arriving code can affect.

5. Persistent managers and ephemeral workers solve different operational problems

Chapter 05 covers executors and Chapter 30 covers fleets/autoscaling in depth. Here the design question is whether a worker should be trusted after running repository code. For untrusted or high-risk workloads, disposal/reimaging is usually safer than attempting perfect cleanup.

6. Version policy: compatibility is an operating requirement

GitLab Runner documentation recommends keeping Runner major.minor aligned with GitLab major.minor. Patch updates also matter because Runner is part of the attack surface and contains executor/network/cache implementations. A production policy should define:

• supported Runner versions and update cadence;
• staging/canary runner pool before broad rollout;
• compatibility tests for executors/helper images/custom tooling;
• recorded version/revision in incident evidence;
• retirement criteria for stale or unsupported managers.

7. Reusing one runner configuration across managers is a fleet decision

The modern workflow permits multiple managers to register with one runner authentication token. That can be useful for horizontally scaled capacity, but it changes evidence and retirement:

• record manager system_id, not only runner ID;
• avoid baking a fixed system ID into reusable machine/container images;
• know whether unregistering/deleting one manager affects other managers;
• rotate authentication material through a controlled fleet procedure;
• preserve per-manager logs externally when workers are ephemeral.

8. Worked decision table

9. Queue time, isolation, and cost are coupled

A single small runner may be cheap but create long queues; an oversized fleet may idle expensively. Do not optimize only job duration. Measure queue time, runner utilization, startup latency, cache/network overhead, and failure rate. Capacity planning comes later in Chapter 30, but the architecture chosen now determines which metrics and scaling levers are available.

Never solve queue pressure by broadening a sensitive runner’s scope or enabling untagged jobs unless the resulting trust expansion is explicitly approved.

10. Minimal production runner record

• Owner/team and purpose.
• Runner ID, scope, tags, run_untagged, protected/pause policy.
• Manager deployment model, system IDs, Runner version/revision, executor.
• Network destinations and denied network zones.
• Credential sources available to jobs.
• Cache/artifact storage and cleanup behavior.
• Update/rotation/de-registration process.
• Monitoring/log-retention and incident contact.
• Expected projects/refs/workload trust level.

Knowledge check

Official references and version notes

• Runners — runner categories, job scheduling, GitLab-hosted versus self-managed runners, and execution flow.
• Manage runners — project/group/instance scope, creation workflow, ownership and pause/resume operations.
• Configure runners — tags, run_untagged, protected runners, authentication-token rotation, and routing behavior.
• Registering runners and new runner creation workflow — current runner authentication-token registration and deprecated legacy registration-token behavior.
• GitLab Runner commands — register, list, verify, run, stop, and unregister lifecycle commands.
• Runner fleet planning — manager system_id identity and modern unregister/delete distinctions.
• Runners API — runner details, managers, status, pause, job history, authentication-token reset, and deletion semantics.
• Security for self-managed runners — remote-code-execution trust, Shell executor risk, persistent-runner residue, isolation, and credential exposure.
• GitLab Runner documentation — current compatibility guidance recommends keeping Runner major.minor aligned with GitLab; GitLab.com users should keep self-managed runners current.