Runner Security, Isolation Boundaries, Privileged Containers, Fork Pipelines, Untrusted Code, and Threat Modeling: Concepts, Architecture, and Mental Model

1. The practical problem: Chapter 30's capacity is also an attack surface

Chapter 30 treated a runner fleet as a capacity system. Chapter 31 keeps that model, but changes the default assumption about the job: repository code, test scripts, build plugins, downloaded dependencies and CI configuration can all be controlled by someone who should not control your runner host. A fast fleet that lets a forked merge request reach a privileged Docker daemon or production credential is not a reliable fleet.

The security question therefore comes before “Which executor is fastest?” First classify who controls the code and ref, then determine which runner may accept it, then inspect what the executor exposes. Only after those boundaries are known should you optimize cache reuse, warm workers or privileged image-building.

2. Mental model: code trust flows into infrastructure trust

A pipeline starts with an exact source event, project, ref and SHA. Those facts determine a trust class; they do not automatically make code benign. The compiled CI configuration decides which jobs exist and which tags they request. GitLab then matches jobs to eligible runners using runner scope, tags and protection rules. The runner manager prepares an executor. That executor exposes some amount of host kernel, filesystem, devices, network and credentials. The job can behave correctly or maliciously. Finally, evidence must survive long enough to investigate, while the execution boundary is cleaned, destroyed or reimaged before it is trusted again.

            flowchart TD
            A[Pipeline source + project + ref + SHA] --> B[Trust classification]
            B --> C[Compiled rules + requested tags]
            C --> D[Runner scope + tags + protected eligibility]
            D --> E[Executor / worker boundary]
            E --> F[Host + network + device + credential exposure]
            F --> G[Repository-controlled job executes]
            G --> H[Job trace + runner/manager evidence]
            H --> I[Destroy / reimage / verified cleanup]
            I --> J[Trust reset before reuse]
          

Each arrow is a distinct control. A protected runner cannot repair an unsafe host socket mount. A non-privileged container cannot compensate for a job that receives a broad production token. An ephemeral VM does not help if its logs disappear before incident collection.

3. Keep the security state domains separate

4. Trust class is about control, not about branch names alone

5. Read-only inspection before changing runners

Start with evidence. In a real GitLab job, these values are safe metadata; do not print any token or secret value:

printf 'source=%s\n' "$CI_PIPELINE_SOURCE"
printf 'project=%s id=%s\n' "$CI_PROJECT_PATH" "$CI_PROJECT_ID"
printf 'ref=%s protected=%s sha=%s\n' "$CI_COMMIT_REF_NAME" "$CI_COMMIT_REF_PROTECTED" "$CI_COMMIT_SHA"
printf 'pipeline=%s job=%s\n' "$CI_PIPELINE_ID" "$CI_JOB_ID"
printf 'job_tags=%s runner_tags=%s\n' "$CI_JOB_TAGS" "$CI_RUNNER_TAGS"
printf 'runner_id=%s runner_version=%s executor=%s\n'   "$CI_RUNNER_ID" "$CI_RUNNER_VERSION" "$CI_RUNNER_EXECUTABLE_ARCH"

CI_JOB_TAGS was added in GitLab 19.3 and exposes the job's configured tags; CI_RUNNER_TAGS identifies the runner's tags. Compare them, but do not mistake a tag match for authorization. Also record runner scope/protection in GitLab and the executor/manager configuration outside the job.

6. Runner eligibility is an intersection, not a single switch

A sensitive job should require tags that only the intended runner pool advertises. The runner itself should be protected when it must not accept ordinary branches. Scope should be as narrow as practical. GitLab documents that protected runners run jobs on protected branches/tags; jobs intended for protected runners should also use tags so they do not fall back to ordinary runners.

For merge-request pipelines, current GitLab behavior is stricter: protected variables/runners can be exposed only when the opt-in setting is enabled, both branches are protected, the triggerer has target-branch permissions, and both branches belong to the same project. A fork MR cannot access those protected resources.

7. Executors change the isolation boundary

8. Credentials and network are part of the executor

A container can remain perfectly contained and still exfiltrate a credential it was legitimately given. Model credential reachability and network reachability as first-class runner properties. An untrusted pool should have no protected deployment variables, no broad cloud identity, no runner-host SSH keys and no route to production/control networks. If a job needs GitLab access, use the narrowest supported identity and remember that even CI_JOB_TOKEN can be stolen while the job runs if the worker is compromised.

Network segmentation should block unnecessary internal services and cloud metadata endpoints while allowing only the dependencies that the job genuinely needs. “Containerized” is not synonymous with “network-isolated.”

9. Fork pipelines have two materially different execution contexts

By default, a fork merge request pipeline is created and runs in the fork project, using the fork project's CI configuration, runners/resources and project variables. A member of the parent project can deliberately run the fork MR pipeline in the parent; that pipeline uses CI configuration from the fork branch but the parent's CI/CD settings/resources/variables and the triggering member's permissions. GitLab shows a warning in the UI because the code can be malicious.

10. Persistent state can turn yesterday's job into today's attack

GitLab warns specifically about GIT_STRATEGY: fetch on shared environments because it reuses the prior worktree. A malicious user can leave executable Git state, and submodule content can remain accessible through reflogs. Use fetch only when all users of that shared environment are trusted. For security-sensitive shared runners, prefer fresh disposable workers; where static workers are unavoidable, consider a fresh clone/empty strategy appropriate to the job and GitLab's FF_ENABLE_JOB_CLEANUP cleanup feature.

Caches, container-image layers and persistent volumes are also reuse channels. They improve performance; they are not trust boundaries.

11. Teardown must not erase the first-failure evidence

For an ephemeral worker, preserve manager logs, pipeline/job IDs, source SHA, runner ID/version/executor, worker identity, job trace, relevant network/provider events and non-secret artifact metadata before the worker disappears. If compromise is plausible, stop assigning new work, isolate the worker, revoke/rotate credentials that could have been exposed, preserve evidence according to policy, then destroy/reimage the worker. A retry creates new evidence and can repeat side effects; it is not an incident-response substitute.

12. Misconceptions that cause runner incidents

Knowledge check

Official references and version notes

Documentation verification date: 2026-09-12. The current stable GitLab Runner patch used as this chapter's reproducibility baseline is 19.3.2 (tagged 2026-09-10). GitLab Runner security guidance treats self-managed runners as remote-code-execution infrastructure, rates Shell executor as high risk for untrusted builds, warns that privileged containers and Docker-socket binding can collapse host isolation, and states that GIT_STRATEGY: fetch on a shared environment is appropriate only when all users are trusted. Since GitLab 18.1, same-project merge-request pipelines can be allowed to use protected variables/runners only when both source and target branches are protected, the triggering user has suitable target-branch access, and both branches belong to the same project; fork merge-request pipelines cannot access those protected resources. The mandatory exercises are local simulations: they require no runner registration token, real secret, privileged container, Docker socket, cloud account, or production network access. The chapter deliberately avoids executing privileged containers or mounting host Docker sockets. Those configurations are shown only as threat-model examples, never as mandatory lab actions.

• Security for self-managed runners — official reference.
• Configure runners — official reference.
• Runner executors — official reference.
• Shell executor — official reference.
• Docker executor — official reference.
• Use Docker to build Docker images — official reference.
• Merge request pipelines and forks — official reference.
• CI/CD pipelines and protected runner behavior — official reference.
• Pipeline types — official reference.
• CI/CD variables — official reference.
• Predefined CI/CD variables — official reference.
• Advanced Runner configuration — official reference.
• Docker Autoscaler executor — official reference.
• GitLab Runner tags — official reference.
• GitLab 19.3 release notes — official reference.

Current assumptions used in this chapter: Version-sensitive YAML, Runner/executor behavior, APIs, security features, policy controls, tiers, and deprecations must be verified against the exact GitLab, GitLab Runner, tool, and external-system versions used in production. Preserve the exact project/ref/SHA, compiled configuration, pipeline/job IDs, runner/tool versions, and external target evidence used for reproducible work.