GitLab Runners, Executors, Tags, Registration, Autoscaling, Isolation, and Security: Concepts, Architecture, and Mental Model

1. The problem: the pipeline is only as trustworthy as the compute that runs it

Chapter 13 ended at the point where GitLab has resolved a job's configuration, variables, permissions, and ref context. None of that code executes inside the GitLab web interface. A GitLab Runner process asks GitLab for eligible jobs and hands each accepted job to an executor. That executor might run commands directly on a persistent host, inside a container, in a Kubernetes pod, or on a newly provisioned ephemeral virtual machine.

This makes a runner a security boundary. Repository-controlled scripts can read source code, use the job token, receive eligible variables, write caches and artifacts, and reach whatever network endpoints the execution environment allows. A runner is therefore not a passive status reporter; it is remote-code-execution infrastructure.

2. Mental model: GitLab schedules; Runner executes

flowchart TD
  C[Commit / MR / pipeline source] --> G[GitLab CI/CD control plane]
  G --> Q[Pending job queue]
  R[Runner manager
authentication token] -->|polls for eligible work| Q
  Q -->|job payload + job token| R
  R --> E{Executor}
  E --> D[Docker container]
  E --> K[Kubernetes pod]
  E --> S[Shell on host]
  E --> A[Ephemeral autoscaled instance]
  D --> O[Logs / artifacts / cache]
  K --> O
  S --> O
  A --> O

3. Runner identity is not job identity

If an attacker steals a runner authentication token, they may be able to clone/impersonate runner capacity. If a malicious job receives a job token, its GitLab access is bounded by the job-token model, but the job can still attack the runner host or network if isolation is weak.

4. Runner scope: where a runner can be considered

Scope answers which projects can even consider this runner. It does not guarantee the runner can execute a particular job. Tags, protected status, paused state, runner health, project enablement, and capacity still apply.

5. Job-to-runner eligibility is an intersection, not a single switch

A useful beginner model is:

eligible = in_scope
        AND runner_accepts_new_jobs
        AND runner_is_available_to_project
        AND runner_has_every_job_tag
        AND untagged_policy_matches
        AND protected_ref_policy_matches
        AND runner_manager_is_online
        AND execution_capacity_is_available

GitLab's documented tag rule is strict: if a job lists multiple tags, a runner must have all of them. A runner may have extra tags. An untagged job additionally requires a runner configured to run untagged jobs. CI/CD runner tags are unrelated to Git tags.

6. Paused, locked, protected, and status mean different things

Do not use “locked” as a synonym for “protected,” and do not interpret “online” as proof that a runner matches a job's tags or scope.

7. Modern registration: create first, then authenticate the manager

The current workflow separates runner creation in GitLab from runner-manager registration on the machine. Creating the runner records ownership, scope, tags, protected/run-untagged policy, and other GitLab-side metadata. GitLab then shows a runner authentication token for registration.

# Conceptual only — never paste a real runner token into course notes or logs.
# 1) Create the project/group/instance runner in GitLab.
# 2) On the isolated runner host, keep the token out of shell history:
read -rsp "Runner authentication token: " RUNNER_AUTH_TOKEN; echo
sudo gitlab-runner register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_AUTH_TOKEN" \
  --executor "docker" \
  --docker-image "alpine:3.22"
unset RUNNER_AUTH_TOKEN

Legacy --registration-token workflows are deprecated and scheduled for removal in GitLab 20.0. On modern instances the old workflow may already be disabled and can return 410 Gone - runner registration disallowed. The correct repair is migration to the runner creation/authentication-token workflow, not re-enabling legacy registration merely to keep an old tutorial working.

8. Executors: where the job actually runs

9. GitLab-hosted runners versus self-managed runners

On GitLab.com, GitLab-hosted runners are integrated instance runners and each normal hosted job runs in newly provisioned infrastructure. They reduce host-maintenance burden, but compute availability, machine type, platform, and quota remain service constraints. Self-managed runners give you executor, network, cache, image, and locality control—but you own patching, isolation, token protection, decommissioning, and capacity.

10. Autoscaling changes persistence, latency, and cost—not just capacity

flowchart TD
  Q[Pending jobs] --> M[Runner manager]
  M --> T[Taskscaler]
  T --> F[Fleeting provider plugin]
  F --> I1[Ephemeral instance A]
  F --> I2[Ephemeral instance B]
  I1 -->|one or bounded jobs| X1[Executor]
  I2 -->|one or bounded jobs| X2[Executor]
  X1 --> C[Cleanup / destroy]
  X2 --> C

11. The runner boundary includes cache, storage, and network

• Workspace: persistent shell hosts can retain source or generated files if cleanup is incomplete.
• Cache: shared or weakly keyed caches can become a cross-job/cross-branch poisoning surface.
• Container volumes: mounting host sockets or sensitive directories can bypass container isolation.
• Network: a job can reach anything the runner environment can route to unless segmentation/policy blocks it.
• Cloud metadata: runner networks should restrict metadata endpoints when jobs do not need them.
• Runner configuration: config.toml contains runner authentication material and must not be exposed to jobs or artifacts.

12. Read-only inspection before any runner change

Start in Settings → CI/CD → Runners for a project or Build → Runners for a group. Record runner ID/description, type/scope, tags, whether it runs untagged jobs, protected state, pause state, status, and version if visible. Do not copy authentication tokens or runner configuration.

# Use a token already configured for glab; do not print it.
PROJECT_ID="12345678"   # disposable example ID

glab api "projects/$PROJECT_ID/runners" \
  --paginate \
  --jq '.[] | {id, description, runner_type, status, paused, tag_list}'

# If your role permits reading a specific runner:
glab api "runners/42" \
  --jq '{id, description, runner_type, status, paused, tag_list, run_untagged, access_level}' 

The API shape is evidence, not a reason to automate changes immediately. First decide which eligibility dimension you are testing.

13. DevOps connection: runner governance is execution governance

A protected variable does not help if unreviewed code can execute on a privileged persistent runner that has internal credentials mounted on the host. Conversely, a carefully isolated ephemeral runner cannot compensate for granting every project broad access to a deployment credential. Production governance composes source trust + pipeline policy + variable policy + runner eligibility + executor isolation + network/storage policy.

14. Common misconceptions

• “Online means eligible.” No: tags, scope, protection, pause state, and capacity still matter.
• “Docker means safe.” Not automatically: privileged mode, host socket mounts, host PID/network modes, or dangerous volumes can defeat isolation.
• “A project runner is always single-project.” It can be enabled for additional projects unless locked/assignment policy prevents that.
• “Runner tags are security labels.” They are routing selectors. Security comes from ownership, protection, executor isolation, and project trust.
• “The old registration token tutorial is still equivalent.” It is deprecated and may be disabled; use runner authentication tokens.

Knowledge check

Summary

Runner design starts with one principle: a runner executes repository-controlled code. Scope determines which projects can consider it; eligibility filters which jobs it can accept; the executor defines isolation; persistence, network, cache, and credentials define blast radius. Modern runner registration separates GitLab-side runner creation from runner-manager authentication and makes ownership auditable.

Official references

• GitLab Docs — Get started with GitLab Runner
• GitLab Docs — Manage runners and runner scope
• GitLab Docs — Configure runners, tags, and protected runners
• GitLab Docs — New runner creation/registration workflow
• GitLab Docs — Register runners
• GitLab Docs — Runner commands and unregister behavior
• GitLab Docs — Runner executors
• GitLab Docs — Docker executor
• GitLab Docs — Shell executor
• GitLab Docs — Kubernetes executor
• GitLab Docs — Docker Autoscaler executor
• GitLab Docs — Instance executor
• GitLab Docs — Self-managed runner security
• GitLab Docs — Runner fleet scaling
• GitLab Docs — Instance-group autoscaler
• GitLab Docs — GitLab-hosted runners
• GitLab Docs — Hosted runners on Linux for GitLab.com
• GitLab Docs — Hosted runners for GitLab Dedicated
• GitLab Docs — Runners API
• GitLab Docs — Token overview / runner authentication tokens
• GitLab Docs — CI/CD YAML tags
• GitLab Docs — Protected branches and CI/CD