GitLab runners

GitLab runners

Assistance managed GitLab runners provide self-hosted CI/CD capacity for GitLab projects, groups, or instances while keeping operations, security, monitoring, and support responsibilities explicit. Use this page when you are moving workloads from shared runners, need private-network access, or need a managed operating model for GitLab CI/CD runner infrastructure.

For the general managed runner onboarding flow, start with Managed runner onboarding. For baseline controls, see Runner security hardening. For support and day-2 signals, see Runner monitoring and support and Troubleshooting. If GitLab itself is part of the managed git server platform, also see the GitLab option runbook; for mixed managed git estates, use the managed runners overview to compare GitLab tags with Gitea/Forgejo labels and Gerrit verification workers.

Where GitLab runners can be attached#

GitLab runners can be registered at several scopes. Assistance will recommend the narrowest practical scope and document who can route jobs to each runner profile.

Scope controls who can use the runner. Tags, protected settings, and project/group permissions control which jobs actually land on it.

Tags and runner selection#

GitLab routes jobs to runners by matching job tags to runner tags. Assistance treats tags as the user-facing capability contract.

Example tag patterns:

A job runs only when a runner has all listed tags and is allowed to serve the project. Use specific tags for privileged jobs. Avoid sensitive names, customer identifiers, internal hostnames, or secret values in tags.

Protected runners and protected branches#

GitLab protected runners can be limited to protected branches and protected tags. Assistance recommends protected runners for deployment jobs, secret-heavy jobs, and runners with private-network access.

Use protected controls together:

• protected branches or tags for release and deployment refs;
• protected variables for production credentials;
• protected environments and approvals where available;
• protected runners with restricted tags such as prod-deploy;
• code-owner or merge approval rules for pipeline changes.

Runner tags are not a substitute for approvals. They route jobs to capacity; they do not decide whether a release is safe.

Executor options at a user level#

GitLab Runner supports multiple executors. Assistance will document which executor each profile uses and what users can expect from it.

Users normally choose tags and job images, not executor internals. If a job needs Docker-in-Docker, privileged containers, GPUs, ARM64, nested virtualization, or private package mirrors, raise that during onboarding so Assistance can assign the correct runner profile.

Autoscaling and capacity#

Assistance can operate fixed-size pools, autoscaling pools, or a hybrid design.

Capacity decisions are based on queue time, job duration, concurrency, cost, and security boundaries. For high-priority projects, Assistance may recommend dedicated tags or a dedicated project/group runner instead of relying on instance-wide capacity.

.gitlab-ci.yml examples#

Route a build to Assistance managed runners#

1
stages:
2
  - test
3
4
variables:
5
  NODE_VERSION: '22'
6
7
test:
8
  stage: test
9
  image: node:${NODE_VERSION}-bookworm
10
  tags:
11
    - assistance
12
    - linux
13
    - x64
14
    - standard
15
  script:
16
    - corepack enable
17
    - pnpm install --frozen-lockfile
18
    - pnpm test
19
  cache:
20
    key:
21
      files:
22
        - pnpm-lock.yaml
23
    paths:
24
      - .pnpm-store/

Use a restricted deployment runner#

1
stages:
2
  - test
3
  - deploy
4
5
deploy_production:
6
  stage: deploy
7
  image: alpine:3.20
8
  tags:
9
    - assistance
10
    - linux
11
    - x64
12
    - prod-deploy
13
    - private-network
14
  rules:
15
    - if: '$CI_COMMIT_BRANCH == "main"'
16
      when: manual
17
  environment:
18
    name: production
19
  script:
20
    - ./scripts/deploy.sh

For production, combine restricted runner tags with protected branches, protected variables, environment approvals, and merge controls.

Variables, secrets, and identity#

Self-hosted runners should not broaden who can access secrets. Keep secret scope and pipeline privileges narrow.

Recommended user practices:

• define CI/CD variables at the project or group level only when that scope is needed;
• mark sensitive variables as masked and protected when appropriate;
• avoid exposing protected variables to unprotected branches or untrusted merge requests;
• prefer short-lived cloud identity federation or deploy tokens over long-lived static keys when available;
• separate build/test variables from production deployment variables;
• avoid dumping environment variables or command traces that expose credentials;
• review who can edit .gitlab-ci.yml, protected branches, environments, and project/group settings.

Assistance can help design variable scope, runner isolation, cloud identity integration, and rotation runbooks. The customer remains responsible for approving secret values, cloud access, and who can modify pipelines.

Artifacts and cache#

GitLab artifacts and cache solve different problems.

Example:

1
build:
2
  stage: build
3
  image: node:22-bookworm
4
  tags: [assistance, linux, x64, standard]
5
  script:
6
    - corepack enable
7
    - pnpm install --frozen-lockfile
8
    - pnpm build
9
  cache:
10
    key:
11
      files:
12
        - pnpm-lock.yaml
13
    paths:
14
      - .pnpm-store/
15
  artifacts:
16
    paths:
17
      - dist/
18
    expire_in: 7 days

Do not cache secrets, credentials, or sensitive generated files. Set artifact retention according to the sensitivity and business need of the output.

Private network access#

GitLab runners are often moved from shared runners to managed self-hosted runners because jobs need controlled access to private systems: package registries, internal APIs, databases used in integration tests, Kubernetes clusters, artifact repositories, or deployment targets.

Before enabling private access, confirm:

• which projects, branches, tags, and environments need access;
• whether the access is build-only, read-only, deploy-only, or administrative;
• which runner tags identify private-network capacity;
• whether jobs can reach production, staging, or only isolated services;
• source IPs, firewall rules, VPN/private link, DNS, and proxy requirements;
• what logs or audit events prove the access was used correctly;
• how access is revoked if a project, token, or runner is compromised.

Private access should be attached to restricted tags and protected runners. Do not allow generic group or instance runners to reach production unless that is explicitly approved and documented.

Registration token handling#

GitLab runner registration uses runner authentication/registration material from the project, group, or instance. Treat it as sensitive provisioning data.

Assistance handles registration according to the agreed operating boundary:

• tokens are generated or exchanged only for approved runner registration;
• token values are not committed, pasted into tickets, or stored in workflow files;
• runner description, scope, tags, executor, protection setting, and lock setting are recorded;
• stale runners are removed from GitLab and from underlying infrastructure;
• token rotation and emergency revocation steps are documented;
• access needed to register project, group, or instance runners is delegated only for the agreed work.

If the customer keeps GitLab admin access internal, the customer can provide short-lived registration material through an approved secure channel or perform registration with Assistance guidance.

Maintenance and operations#

Assistance managed GitLab runners include a documented day-2 operating model. The exact activities depend on the contract, but typical coverage includes:

• runner binary, executor, operating system, and base image updates;
• autoscaler, Kubernetes, VM, or host health monitoring;
• queue time, concurrency, failure rate, utilization, and capacity review;
• cache and artifact-storage health checks where in scope;
• disk pressure, stale workspace, and Docker layer cleanup;
• tag, scope, protection, and project/group access changes through approved requests;
• incident triage and GitLab/provider escalation when platform behavior is involved;
• periodic review of protected runners, variables, private-network access, and runner drift.

See Runner monitoring and support for the support workflow and Troubleshooting for escalation inputs.

Troubleshooting quick checks#

When opening a support request, include the project path, pipeline URL, job name, tags, runner name if visible, approximate time, recent changes, and business impact. Do not paste secrets or registration tokens into tickets.

Migration from shared runners#

A safe migration from GitLab shared runners is incremental.

1. Inventory current pipelines — collect stages, job tags, images, duration, queue time, failure patterns, cache/artifact use, variables, and deployment paths.
2. Select pilot jobs — start with slow or expensive build/test jobs that do not carry production deployment risk.
3. Define runner tags — map shared-runner behavior to Assistance tags such as assistance, linux, x64, and standard.
4. Validate executor behavior — confirm images, services, Docker-in-Docker, caches, artifacts, and shell assumptions work on the managed profile.
5. Move private or privileged jobs later — deployment and private-network jobs need protected runners, protected variables, approvals, and rollback notes.
6. Compare results — measure queue time, duration, failure rate, cost, and developer experience.
7. Document rollback — keep a known path back to shared runners or an alternate managed profile until the migration is accepted.

Shared runners may remain appropriate for simple low-risk jobs, public projects, or workloads that do not justify a managed operating surface.

EU security and compliance notes#

Assistance can design GitLab runner operations to support EU-aligned security and data-residency expectations, but legal outcomes depend on the customer environment, data, vendors, and contract.

Confirm during onboarding:

• whether GitLab is SaaS, self-managed, or Assistance-supported, and where runner compute is hosted;
• whether source code, artifacts, caches, logs, container images, and telemetry remain in agreed EU locations;
• data classification for pipeline inputs, generated artifacts, logs, and test datasets;
• access-review cadence for GitLab admins, project/group maintainers, environment approvers, cloud roles, and Assistance operators;
• retention periods for artifacts, traces, runner logs, and operational evidence;
• subprocessors and external services involved, including GitLab, cloud providers, registries, cache backends, and monitoring tools.

Assistance can provide technical evidence, operational records, and hardening recommendations. Formal legal advice, regulatory filings, and guaranteed compliance positions must come from the customer's legal/compliance process or from explicit contractual terms.

Customer and Assistance responsibilities#

GitLab, Gitea, and Forgejo estates#

Some customers operate GitLab alongside Gerrit, Gitea, or Forgejo. Assistance can help align runner labels/tags, network boundaries, and support workflows across platforms, but each platform needs its own registration and security model. GitLab routes jobs with runner tags and scopes, Gerrit usually routes verification through CI adapters that report labels back to changes, and Gitea/Forgejo Actions route with runs-on labels. If another managed git server is in scope, include those repositories and runner requirements in onboarding so the platform-specific runbook can be created or updated before rollout.

Related docs and services#

• Managed runner onboarding
• Managed runners overview
• Runner security hardening
• Runner monitoring and support
• Troubleshooting
• Managed runners
• GitLab option runbook
• CI/CD audit
• DevOps as a Service
• SRE as a Service
• Release readiness
• Incident response runbook

Getting started#

Open an onboarding or support request with the GitLab scope, project/group paths, required tags, executor needs, protected-runner expectations, network needs, deadline, and current .gitlab-ci.yml examples. Assistance will confirm the operating boundary before registering runners or making production-impacting changes.