GitLab Runner Architecture, Registration, Runner Managers, Job Execution, and Lifecycle: Concepts, Architecture, and Mental Model

1. The problem: a queued job needs infrastructure, not just YAML

Chapter 03 made the job execution boundary visible. Chapter 04 moves one layer deeper: who is allowed to execute that job, where the execution process lives, how GitLab recognizes it, and what remains after the job ends. A pipeline can compile perfectly and still wait forever because no runner is eligible. Conversely, a broadly scoped runner can execute far more repository code than its operator intended.

The core operational habit is to describe a runner precisely. “We have a runner” is incomplete. A useful statement is: “project runner #123 is unpaused, restricted to tag ch04-lab, does not run untagged jobs, has one Linux/amd64 manager system ID, is running GitLab Runner 19.3.1 with the Shell executor in a disposable lab container, and has no production credentials.”

2. The runner execution model

            flowchart TD
              A[Queued job requirements] --> B[Scope + tags + protection + pause state]
              B --> C[Eligible runner configuration]
              C --> D[Runner manager polls GitLab]
              D --> E[Manager system_id + version + executor]
              E --> F[Executor prepares job environment]
              F --> G[Trusted job executes]
              G --> H[Trace / artifacts / job status uploaded]
              H --> I[Workspace cleanup]
              I --> J[Manager returns to idle / available state]
          

The first half of the diagram is GitLab scheduling and runner eligibility; the second half is a particular manager and executor doing work. A job that cannot pass the eligibility boundary remains pending and never reaches the executor.

3. Runner configuration and runner manager are not the same object

The modern creation workflow intentionally separates the reusable GitLab-side runner configuration from individual managers. The same authentication token can register the configuration on multiple hosts, and GitLab distinguishes those managers with system IDs. This is why “unregister the manager” and “delete the runner” are different lifecycle operations.

4. Registration is now a two-step ownership workflow

The recommended workflow is: (1) create a project/group/instance runner in GitLab with its scope and routing policy, then (2) register a manager using the runner authentication token. Older registration tokens are legacy, disabled by default in newer GitLab configurations, and scheduled for removal in GitLab 20.0.

# Modern shape — token value is supplied securely and never echoed.
gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.example.com/" \
  --token "$RUNNER_AUTH_TOKEN" \
  --executor "shell" \
  --description "ch04-disposable-manager"

With the modern authentication-token workflow, runner properties such as tags, protected access, run_untagged, and similar routing controls are configured when the runner object is created in GitLab or through the supported API. Do not rely on legacy registration-command flags to define those policies.

5. Scope is the first blast-radius boundary

Prefer the narrowest scope that serves the requirement. Broad scope is not “more flexible” when the runner can reach sensitive networks, caches, signing keys, deployment credentials, or host state.

6. Tags, untagged jobs, and protected runners are scheduling controls

Runner tags are not Git tags. They are capabilities/selectors used during runner matching. A runner must satisfy all tags requested by a job. If a runner has [linux, docker, gpu], it can satisfy a job requesting [linux, docker]; a runner with only [linux, docker] cannot satisfy a job that also requests gpu.

trusted_runner_probe:
  tags:
    - ch04-lab
  script:
    - printf 'runner_id=%s
' "$CI_RUNNER_ID"
    - printf 'runner_description=%s
' "$CI_RUNNER_DESCRIPTION"
    - printf 'runner_tags=%s
' "$CI_RUNNER_TAGS"
    - printf 'runner_version=%s
' "$CI_RUNNER_VERSION"
    - printf 'runner_arch=%s
' "$CI_RUNNER_EXECUTABLE_ARCH"

For a dedicated capability runner, disabling “run untagged jobs” prevents unrelated untagged jobs from drifting onto it. Protected runners add another trust boundary by limiting eligible refs according to GitLab protected-ref rules. Tags and protection complement one another; neither substitutes for executor/host isolation.

7. Paused, online, offline, stale, and never-contacted answer different questions

8. Version and manager identity are part of evidence

GitLab recommends keeping GitLab Runner major.minor synchronized with the GitLab major.minor version. Older/newer combinations can work, but features can depend on matching versions. For GitLab.com, which changes continuously, self-managed runner operators should keep Runner current.

Record the manager system_id, Runner version/revision, platform, and architecture when diagnosing routing or compatibility. If one runner configuration has multiple managers, “runner #123” alone does not identify which machine executed a job.

9. The runner authentication token is infrastructure credential material

The runner authentication token lives on the runner manager host in config.toml and lets a process authenticate as that runner configuration. An attacker who steals it may be able to clone the runner identity. It therefore belongs in host secret storage, not repository variables, artifacts, job logs, screenshots, or course evidence.

Job execution environments should receive the job token appropriate to the job, not the runner authentication token. If the authentication token is exposed, rotate/reset it and re-establish manager configuration according to current GitLab guidance; masking the old string in a log does not undo exposure.

10. Read-only inspection before touching a runner

• Which runner ID and scope own the capability?
• What tags, protected state, run_untagged, and pause policy are configured?
• How many managers exist under that runner configuration?
• What are their system IDs, versions, platforms, architectures, contact times, and statuses?
• Which executor does the manager use, and what trust boundary does it create?
• Which jobs has the runner processed, and are there pending jobs that actually match it?
• What host/network/cache/credential residue can survive between jobs?

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.