When this helps
A merge request pipeline runs repository code before anyone has accepted the change. That code might come from a teammate, a fork, a dependency update, or a coding agent. Approving the contributor doesn't make the unreviewed code safe to run beside release credentials or on a host that can reach production.
The runner decides where the job executes, and the job receives whatever the host, network, cache, and credentials make available. If one pool handles both unreviewed changes and protected signing or deployment work, a pipeline can become an unintended route from proposed code to protected resources.
Group jobs around the access they need. General tests can run on disposable workers with little network access. Protected builds can use another pool with narrowly scoped credentials. Signing and deployment jobs can use a smaller pool that reaches only its intended destination. These access differences deserve particular attention when you manage your own runners or connect CI/CD to private networks. It doesn't require a separate runner for every project.
GitLab-hosted runners already give each GitLab.com job a newly provisioned virtual machine that is deleted after the job. That takes care of host reuse for those jobs, but you'll still want a separate path for work that needs protected variables, a private network, signing material, or deployment access.
Plan the approach
A practical runner design usually includes these choices:
- Group jobs by what they can reach. Start with unreviewed changes, protected builds, and release or deployment work. Add another group only when it needs meaningfully different privileges or infrastructure.
- Limit runner scope to the projects that need it. Project, group, and instance scope decide which projects can use a runner. A broadly shared pool works for jobs with similar needs; a protected deployment pool should normally have a smaller audience.
- Treat tags as routing, not authorization. Give each pool clear tags and leave Run untagged jobs off for protected or privileged pools. Pair tags with protected-runner settings, branch rules, variable protection, and network controls.
- Prefer fresh workers for unreviewed code. GitLab-hosted runners provide one ephemeral virtual machine per job. For a self-managed autoscaled fleet,
capacity_per_instance = 1andmax_use_count = 1create the same one-job lifecycle with the Instance executor. - Keep the runner manager away from protected systems. The manager needs to reach GitLab and the infrastructure provider, but it doesn't need to run on the GitLab host or share a network with production services.
- Give each pool only the network and credentials its jobs need. General tests rarely need a deployment network. Release jobs don't need broad access to every production environment.
- Use short-lived job credentials where the target supports them. Protect runner authentication tokens and
config.toml, and keep long-lived secrets out of repository files and pipeline definitions. - Size security and capacity together. Review queue time, provisioning time, active workers, failures, and idle cost by pool. A protected pool that is always stuck will encourage teams to look for another route.
Understand the access each pool needs
Begin with an inventory of the runners that can pick up jobs from the affected projects. For each runner or autoscaled pool, record:
| What to record | What it helps you answer |
|---|---|
| Owner and backup | Who can change, pause, patch, or replace the pool? |
| Instance, group, or project scope | Which projects can ask the runner to execute code? |
| Tags and Run untagged jobs | Which jobs can be routed to the pool? |
| Protected-runner setting | Can unprotected refs use the pool, and are merge request pipelines enabled? |
| Executor and privileged mode | How much access can a job gain on its worker? |
| Host reuse and cleanup | Can one job leave code or credentials for a later job? |
| Network destinations | Which registries, services, cloud APIs, and environments can a job reach? |
| Variables and workload identity | Which credentials can a job request or receive? |
| Resource and concurrency limits | Can one project or job exhaust the pool? |
| Queue, provisioning, use, and failure measures | Does the pool have enough capacity for its purpose? |
Then choose a small set of workload groups. For example:
| Workload group | Typical work | Runner characteristics |
|---|---|---|
| Unreviewed contributions | Forks, unprotected branches, merge requests, and agent-authored changes before approval | Disposable worker, no protected variables, no signing or deployment access, restricted network |
| Protected build and package | Builds from protected refs, package publication, or controlled release preparation | Protected runner, narrowly scoped registry access, fresh worker where practical |
| Signing and deployment | Artifact signing, production deployment, or protected environment jobs | Small protected pool, project or group scope, short-lived credentials, network access only to named targets |
| Specialized privileged work | Jobs that need privileged containers, hardware, or a trusted Shell executor | Dedicated pool, isolated disposable host, named owner, narrow project set, no untagged jobs |
Runner capabilities are available on GitLab.com, GitLab Self-Managed, and GitLab Dedicated. GitLab.com and GitLab Dedicated can use GitLab-hosted runners, and all three offerings can use runners you manage. GitLab Dedicated for Government customers build and manage FIPS-compliant runners outside the tenant. Check the current offering guidance before choosing who operates each pool.
Design and verify the runner pools
Trace one job from request to access
Pick one ordinary merge request pipeline and one protected release or deployment pipeline. Follow each job from its .gitlab-ci.yml definition to the runner that accepts it. Record the runner scope, matching tags, protected status, executor, worker lifecycle, variables, network destinations, and any cloud identity the job can request.
This trace often finds a mismatch before any configuration changes are needed. A job named test may run on a group runner that can reach a production subnet. A deployment job may use a broad instance runner because its tag happens to match. A protected pool may still accept untagged work or merge request pipelines. The job name doesn't tell you what the worker can do.
Route unreviewed work to the least-connected pool
Use a separate tag for the unreviewed-work pool and reference it in the relevant jobs. Leave Run untagged jobs disabled on every pool that has protected credentials or private network access. If you keep a general runner for untagged jobs, make it the least-connected option.
Runner scope limits which projects can request a runner, while tags match a job to a runner. Neither one replaces worker isolation or network rules. A group runner used by several projects can still be a good fit when every project has the same trust level and the workers are disposable. Consider a project runner when one project's release path needs access that shouldn't be shared.
Protected runners can be limited to jobs on protected branches or protected tags. A project can also allow merge request pipelines to access protected variables and runners when both branches are protected, both belong to the same project, and the user triggering the pipeline has permission to merge or push to the target branch. Fork merge request pipelines can't access these protected resources. If you enable this option, test the source- and target-branch combinations your teams use and confirm which jobs receive access.
Choose a worker lifecycle that fits the workload
For unreviewed work, a fresh worker prevents one job from leaving a modified checkout, process, image, or credential for the next job. GitLab-hosted runners on GitLab.com create a dedicated virtual machine for each job and delete it after completion.
For self-managed autoscaling, the Instance or Docker Autoscaler executor is the current direction. With the Instance executor, capacity_per_instance = 1 and max_use_count = 1 assign one job to an instance before it is replaced. A reusable worker can be reasonable for trusted jobs, but it should be a deliberate choice with cleanup, patching, and access controls.
The Shell executor runs jobs with the runner user's permissions and should be reserved for trusted work. A privileged Docker job can gain root-level control of its host, so it belongs on an isolated, ephemeral virtual machine rather than beside unrelated jobs.
Docker Machine was deprecated in GitLab 17.5 and is scheduled for removal in GitLab 20.0. If a pool still uses the Docker Machine executor, plan its move to the GitLab Runner Autoscaler instead of expanding it.
Limit the manager, network, and credentials
Place self-managed runner managers on dedicated hosts away from the GitLab application and other critical systems. The manager needs cloud permissions to create and remove workers, which makes its own host and credentials worth protecting even when jobs run elsewhere.
Give worker networks outbound access to GitLab, required package sources, and the specific services needed by their workload group. Filter access to cloud metadata services where appropriate. A deployment pool can use a route to one environment without gaining a route to every environment. An unreviewed-work pool shouldn't be able to reach signing systems or production endpoints at all.
Let jobs request short-lived credentials through workload identity where the target supports it. For stored job secrets, use a secrets provider or appropriately protected and scoped CI/CD variables, and keep them out of repository files and reusable runner images. Check which jobs can obtain each secret: masking its log output doesn't limit what the job's code can do with it.
The runner's own authentication token is different from a job secret. Registration stores it in the manager's config.toml, so restrict access to that file and the manager host. Use GitLab's supported token rotation or reset mechanism, and verify each manager still connects after rotation. When retiring a manager, remove its configuration and credentials; if it shares a runner token with other managers, coordinate a token reset so the remaining managers can continue. Reset a compromised token promptly and investigate where it was used.
Tune capacity without weakening the design
Track queue time, provisioning time, running workers, idle workers, job duration, and failures separately for each pool. These measures help distinguish a slow job from a pool that is too small or slow to provision.
Idle workers reduce start time but cost more. Disposable workers reduce carry-over between jobs but provision more often and may reuse less local cache. Start with enough idle capacity for normal demand, review peak periods, and change one autoscaling setting at a time. For a pool that supports an important release path, use at least two runner managers with the same tags so one manager failure doesn't stop every job.
Try the paths that should succeed and fail
Use a representative project to check the design before applying it more broadly:
- An unprotected branch and an ordinary merge request should run on the unreviewed-work pool and should not receive protected variables.
- A job from that pool should fail to connect to a harmless test endpoint placed behind the same network rule that protects the real destination.
- A protected build should reach only its intended registry or package destination.
- A deployment job should run only from the protected path you selected and should receive a credential limited to the intended environment.
- A disposable worker should disappear after its job, and a later job should receive a different worker without the earlier checkout.
- Pausing a pool or revoking its authentication token should stop it from accepting new jobs.
- Taking one runner manager out of service should leave enough capacity for the jobs the pool is meant to protect.
Record the job links, runner IDs, worker IDs, route checks, and expected failures. Repeat the checks after changing runner scope, tags, executor, network rules, credentials, or autoscaling settings.
Tradeoffs
If the inventory identifies long-lived keys or tokens in a protected pool, replacing long-lived pipeline credentials provides the migration approach. If jobs have the right isolation but developers still wait too long, improving pipeline feedback helps separate runner queues from delays inside the pipeline.
- More pools mean more operating work. Each pool needs an owner, patching, monitoring, capacity review, and a retirement path. Keep the number tied to real access differences.
- Fresh workers can cost more and start more slowly. Pre-provisioned idle capacity and shared remote caches can help, but a cache shouldn't expose one trust group to another.
- Narrow scope can reduce flexibility. A project runner makes ownership clear but can sit idle. A group runner improves use when the participating projects need the same access.
- Tags are easy to copy. A copied tag can route a job, so the protected setting, worker lifecycle, credentials, and network rules must still enforce the intended result.
- Hosted and self-managed runners solve different needs. Hosted runners reduce fleet maintenance and provide ephemeral workers. Consider self-managed runners for private networks, specialized hardware, custom images, or requirements that the hosted fleet doesn't meet.
- A protected runner isn't automatically a safe deployment system. It can still reuse a compromised host, carry broad credentials, or reach more networks than the job needs.
- A fast queue can hide an oversized fleet. Review idle workers and cost beside job start time. A cheaper pool that delays every review or release may simply move the cost to contributors.
Further Reading
- Security for self-managed runners explains executor risks, shared-host reuse, privileged jobs, network segmentation, and cleanup.
- Manage runners explains instance, group, and project runner scope.
- Configure runners covers protected runners, merge request pipelines, tags, and untagged jobs.
- Use external secrets in CI/CD explains job-requested secrets and authentication to supported providers; its built-in integrations are available in Premium and Ultimate.
- GitLab-hosted runners describes the available hosted fleets and GitLab.com's one-job ephemeral virtual machines.
- GitLab Runner Autoscaling and the Instance executor cover current autoscaling choices and one-job instance settings.
- Docker Machine executor explains its deprecation and migration to the GitLab Runner Autoscaler.
- GitLab Dedicated for Government secure configuration guide explains the customer's runner responsibilities and FIPS requirement.
- Runner trust zones for mixed CI/CD workloads shows how unreviewed, protected-build, and deployment pools fit together as one system, including access, capacity, failure, and recovery paths.