GitLab Compatibility Project Onboarding Guide

Compatibility-only guide for enrolling a GitLab project on the shared HPA runner pool. Current main is GitHub-first; use Self-Service Enrollment for the primary shared lane contract.

Prerequisites

1. Project location: Your project must be in a group where runners are registered. Runners only propagate downward in the GitLab group hierarchy. If your project is in a sibling subgroup, you need additional runner registrations scoped to your group. For self-contained overlay stacks, register those extra project or subgroup bindings directly in your overlay-owned runner configuration.

2. CI variables: Nix jobs require ATTIC_TOKEN (masked, protected) for cache access. Deployment jobs may need CI_SSH_PRIVATE_KEY and environment-specific variables.

3. Runner visibility: Verify runners appear in your project under Settings > CI/CD > Runners. If they don’t, the runner group scope needs updating.

Step 1: Choose Runners

Use the Runner Selection Guide to map each CI job to a runner type:

Step 2: Add Tags to Jobs

Add tags: to each job in your .gitlab-ci.yml:

Before:

lint:python:
  stage: validate
  image: python:3.11-slim
  script:
    - ruff check src/

After:

lint:python:
  stage: validate
  tags: [docker]
  image: python:3.11-slim
  script:
    - ruff check src/

Jobs without tags: continue running on GitLab SaaS shared runners.

Step 3: Configure Cache (Nix Jobs)

Nix runners inject ATTIC_SERVER and ATTIC_CACHE environment variables for the cluster-local Attic cache. If your project uses its own Attic cache, set these variables at the job level — job-level variables override runner-injected values:

build:nix:
  tags: [nix]
  extends: .nix-attic
  variables:
    ATTIC_SERVER: "https://your-cache.example.com"
    ATTIC_CACHE: "your-cache-name"

Step 4: Verify Pipeline

1. Push your branch and check the pipeline
2. Click on a tagged job — the runner name should show a matching shared runner such as tinyland-docker, tinyland-nix, or another installation-specific runner name for your pool.
3. Check job duration against baseline (SaaS runner times)
4. For Nix jobs, verify cache hits in the build log

Historical Compatibility Example: upgrading-dw

The upgrading-dw example is retained as GitLab compatibility history. Do not copy it as the normal product shape for new GitHub-first or pooled-substrate adoption. The current product contract is shared capability classes plus shared cache attachment, not project-specific runner fleets.

That project migrated CI jobs onto the compatibility runner pool:

Project-level Attic overrides are allowed only when a repo intentionally has a separate internal cache namespace. They are not the default onboarding path. Prefer the runner-provided ATTIC_SERVER, ATTIC_CACHE, and BAZEL_REMOTE_CACHE values unless there is a documented reason to override the shared substrate.