Skip to content

Private CI runners

The big picture: CI pipeline says what the pipeline runs. This page says what it runs on. Register general-purpose runners once, at the group level, so every project (including ones created later) gets CI with no setup. Keep scarce hardware, such as an Apple silicon Mac, behind explicit tags. Point the runners at one shared object-storage bucket so the cache survives across hosts. The pipeline-side half of CI speed (a prebuilt base image, shallow clones, needs:) is in Making the pipeline fast.

Why it matters: an adopter with more than one project needs a runner strategy, not a per-project runner. A strategy decides who pays for compute, which jobs can reach your network, and whether a cache hit is common or rare.

How it works: the seven sections below. Everything about GitLab behavior links to GitLab’s docs; where a setting depends on tier or on GitLab.com versus self-managed, the text says so. Vendor products named in the cache section are examples, not endorsements.

  • Control of hardware and architecture. You choose CPU, memory, disk and architecture (AMD64, ARM64, Apple silicon), and you can add a GPU or a large-memory host.
  • No compute-minute quota. Jobs run on machines you already pay for.
  • Secrets and network access stay inside your infrastructure. A job can reach an internal registry, database or deploy target without exposing it to the internet.
  • Warm caches and image layers. A long-lived host keeps pulled images and build caches between jobs.
  • No noisy neighbors on a shared IP. Anonymous Docker Hub pulls are rate limited per runner IP; see the registry-mirror tip.

The cost: you own patching, capacity, and runner security. A runner that is not updated, or that is shared with untrusted code, is a way into your network (see section 7).

See Runner scopes and the GitLab Runner overview.

A group runner serves every project and subgroup in the group, including projects created after the runner. A new project needs no per-project runner setup. Creating a group runner needs the Owner role on the group; the page applies to the Free, Premium and Ultimate tiers, on GitLab.com and self-managed.

  1. In the group, go to Build > Runners and select Create group runner.
  2. Add tags (optional for a general-purpose runner) and select Create runner.
  3. Follow the on-screen steps on the runner host to register it with the authentication token. Registration with a registration token is deprecated; see the authentication-token workflow and Registering runners.

Turn on Run untagged jobs on the general-purpose group runners. All of Blueprint’s governance jobs have no tags:, so a runner that does not run untagged jobs leaves them stuck. With the Run untagged jobs checkbox selected, they are picked up and nobody edits .gitlab-ci.yml. See Configure runners.

3. Special-purpose runners are tagged-only

Section titled “3. Special-purpose runners are tagged-only”

Some hardware only some jobs need: for example a self-hosted runner on Apple silicon for macOS, iOS and native ARM64 builds. Treat it differently from the general fleet:

  • Leave Run untagged jobs off. A runner set to run only tagged jobs ignores untagged ones, so scarce, slow-to-scale hardware does not pick up governance jobs.

  • Give it explicit tags, such as macos and arm64. A job is sent to a runner only if the runner has every tag the job lists.

  • Let only the jobs that need it opt in with tags::

    ios-build:
    tags: [macos, arm64]
    script:
    - xcodebuild -scheme App build

If owning a Mac is not worth it, GitLab also offers hosted macOS runners. As checked on 2026-10-27, they are available on GitLab.com only, on the Premium and Ultimate tiers (and open source programs), run on Apple silicon, and are in beta. Check the page for current status.

4. One runner host can serve several groups

Section titled “4. One runner host can serve several groups”

A runner registration belongs to one group. But one gitlab-runner host’s config.toml can hold several [[runners]] entries, and each entry can be registered with a different group’s token. Two groups can therefore share the same machines.

This is a generic illustration, not a description of any real installation. One host, two groups, one registration each:

# /etc/gitlab-runner/config.toml (illustration only; tokens elided)
concurrent = 8 # ceiling across all registrations on this host
[[runners]]
name = "group-a-docker"
url = "https://gitlab.example.com"
token = "<group A authentication token>"
executor = "docker"
limit = 4 # this registration never uses more than 4 slots
[runners.docker]
image = "alpine:3.23"
[[runners]]
name = "group-b-docker"
url = "https://gitlab.example.com"
token = "<group B authentication token>"
executor = "docker"
limit = 4
[runners.docker]
image = "alpine:3.23"

concurrent caps jobs across all registrations; limit caps one registration. See config.toml.

The tradeoff: shared hosts mean shared capacity and a shared blast radius. A busy group can starve the other, and a compromised job on the host is a problem for both. Set limit on every registration so one group cannot take all the slots, and prefer an isolating executor (Docker or Kubernetes) over the shell executor on a shared host.

Keep the real topology (hostnames, tokens, which groups share which hosts) in your private <project>-devops repo, not in public docs; see Deployment options.

Runner Pick it when Isolation Scaling Typical tags
Docker executor, AMD64 The default general-purpose runner. Needs Docker on the runner host. Each job runs in a fresh container. Add hosts or raise concurrent. none (runs untagged), or docker, amd64
Kubernetes executor, AMD64 (Helm chart) You already run a cluster, or want a pod per job and autoscaling. Each job runs in its own pod. The cluster scales the pods. none, or k8s
Apple silicon (shell executor, or a VM-based setup on macOS) Xcode, iOS and native ARM64 builds. Shell executor: none between jobs; jobs run on the host as the runner user. A VM or autoscaler setup gives per-job isolation. Slow and manual; hardware is scarce. macos, arm64

Notes:

  • The Docker and Kubernetes executors give each job a clean environment; the Kubernetes one starts a new pod per job. The official way to run it is the Helm chart.
  • The shell executor runs builds directly on the host with no clean environment between jobs, which is a security consideration (GitLab’s executors page also lists it as in maintenance mode): see section 7. For macOS setup see Install on macOS and the executors overview, which lists the other macOS options.
  • Multi-arch container images. On Apple silicon you can build native ARM64 images. On AMD64 you build ARM64 with buildx and QEMU emulation, which Docker says “can be much slower than native builds” (see Docker’s multi-platform builds). For building images in GitLab CI see Building Docker images, and for scaling many runners, Fleet scaling.

Without a shared cache, each runner host keeps its own local cache, so a job that lands on a different host (or a fresh autoscaled pod) misses. Point [runners.cache] at an object-storage bucket and hits survive across hosts. Background: Caching in CI and Speed up job execution.

Minimal config.toml (from GitLab’s advanced configuration):

[runners.cache]
Type = "s3"
Path = "path/to/prefix"
Shared = false
[runners.cache.s3]
ServerAddress = "s3.example.com" # host:port of any S3-compatible endpoint
AccessKey = "<bucket-scoped access key>"
SecretKey = "<bucket-scoped secret key>"
BucketName = "runners-cache"
BucketLocation = "us-east-1" # region name
Insecure = false # true only if reached over plain HTTP

Type can also be gcs ([runners.cache.gcs]) or azure ([runners.cache.azure]), natively. Shared = true lets different runners read each other’s cache.

Kind What it is, who runs it Pick it when Examples
Managed cloud object storage Run by a cloud provider; you run nothing. Your runners already sit in that cloud. Watch egress charges when runners are elsewhere. AWS S3, Google Cloud Storage and Azure Blob (both native cache types)
S3-compatible hosted service Run by a provider with an S3 API. Runners are outside the big clouds. Compare each provider’s current egress pricing, and check how complete its S3 compatibility is. Cloudflare R2, Backblaze B2
Storage array or NAS with object storage turned on Hardware you already run, with an S3 endpoint enabled. You want cache traffic on the LAN and no new software to operate; it reuses hardware and backups you already have. NetApp ONTAP S3, Pure Storage FlashBlade, Dell ObjectScale, TrueNAS (check the current version’s docs for S3 support; its older MinIO-based service is deprecated)
Software-only, self-hosted You run it on commodity hardware or in the cluster: disks, replication, upgrades are yours. You have no array and no cloud, and accept the operations work. SeaweedFS, Ceph RGW, Garage, MinIO (see below)

MinIO status (checked 2026-10-27). The community repository is licensed AGPL v3 but was archived by its owner on 2026-04-25 and is read-only; its README says it is no longer maintained and that pre-compiled binaries of the community version are no longer provided (older ones remain, without updates), and points to the vendor’s AIStor products. Verify the current state before choosing it for a new setup.

Every product above is an example. Compatibility varies: Cloudflare R2 documents that some S3 parameters are unimplemented, and Backblaze B2 documents gaps such as object tagging. Test a cache upload and download before you rely on it.

Guidance:

  • Put the cache close to the runners. A cache across a WAN can be slower than no cache.
  • Treat it as disposable. Set a lifecycle or expiry rule on the bucket where the store supports one, so old caches do not accumulate (R2, for example, supports object lifecycle rules).
  • Give the runner a credential scoped to that one bucket, with no access to anything else.
  • Mark runners that hold deploy credentials as Protected. The Protected checkbox restricts a runner to jobs on protected branches (or protected tags), so a job from an arbitrary branch cannot read the credentials. See Configure runners.
  • Never run untrusted fork or MR code on a privileged or shell-executor runner. GitLab warns that the shell executor has “high-security risks” to the host and network, should be used “only for running trusted builds”, and that a job on a non-ephemeral runner shared across projects can compromise other repositories. Any user with the Developer role on a project can run code on its runners.
  • Patch the runner and its host, and prefer ephemeral, isolating executors for shared hosts.

See Runner security.