GitLab Runner Architecture, Registration, Runner Managers, Job Execution, and Lifecycle: Guided Hands-On Workflow and Core Operations

1. Preflight: prove the project and local runtime are disposable

LAB_TAG="ch04-lab"
RUNNER_NAME="ch04-disposable-manager"
RUNNER_CONTAINER="ch04-runner-manager"
RUNNER_VOLUME="ch04-runner-config"
EVIDENCE="ch04-evidence"
mkdir -p "$EVIDENCE"

git status --short --branch
git rev-parse HEAD | tee "$EVIDENCE/head-before.txt"
docker version --format '{{.Server.Version}}'

docker ps -a --filter "name=^/${RUNNER_CONTAINER}$"
docker volume ls --filter "name=^${RUNNER_VOLUME}$"

If either exact Docker resource already exists and was not created for this lab, stop. Choose new disposable names rather than deleting unknown infrastructure. In GitLab, inspect Settings → CI/CD → Runners and record existing runner IDs/descriptions without copying any token.

2. Create one narrowly scoped project runner in GitLab

In the disposable project, open Settings → CI/CD → Runners → Create project runner. Use these deliberate settings:

• Description: ch04-disposable-runner.
• Tags: exactly ch04-lab.
• Run untagged: disabled.
• Protected: disabled for this disposable unprotected lab branch; do not alter a production protection policy for the exercise.
• Scope: project only.

After creation, record the runner ID and routing settings. GitLab displays a runner authentication token for registration. Put it into a temporary shell variable or secure prompt input; never echo, paste into notes, or commit it.

# Example only: assign the secret in your local shell without printing it.
read -rsp "Runner authentication token: " RUNNER_AUTH_TOKEN
printf '
'
test -n "$RUNNER_AUTH_TOKEN"
# Do not run: echo "$RUNNER_AUTH_TOKEN"

3. Register one isolated manager with Runner v19.3.1

docker volume create "$RUNNER_VOLUME"

docker run --rm \
  -v "$RUNNER_VOLUME:/etc/gitlab-runner" \
  gitlab/gitlab-runner:v19.3.1 register \
  --non-interactive \
  --url "https://gitlab.com/" \
  --token "$RUNNER_AUTH_TOKEN" \
  --executor "shell" \
  --description "$RUNNER_NAME"

unset RUNNER_AUTH_TOKEN

docker run -d \
  --name "$RUNNER_CONTAINER" \
  --restart no \
  -v "$RUNNER_VOLUME:/etc/gitlab-runner" \
  gitlab/gitlab-runner:v19.3.1 run

This lab intentionally uses a Shell executor inside a disposable runner container for a synthetic trusted job and does not mount the host Docker socket. Shell executor is high risk on a shared/persistent host; Chapter 05 compares executors in depth. The container here is a disposable teaching boundary, not a recommendation for production runner architecture.

4. Verify registration without reading the token

docker exec "$RUNNER_CONTAINER" gitlab-runner --version 
docker exec "$RUNNER_CONTAINER" gitlab-runner list 
docker exec "$RUNNER_CONTAINER" gitlab-runner verify

In the GitLab runner UI, verify the runner is no longer “never contacted” and inspect its manager details if available: system ID, version, platform/architecture, contacted time, status, and job execution state. Save screenshots only if they do not reveal authentication material.

5. Route one trusted job exclusively to the lab runner

stages: [inspect]

runner_identity_probe:
  stage: inspect
  tags:
    - ch04-lab
  script:
    - printf 'pipeline_id=%s
' "$CI_PIPELINE_ID"
    - printf 'job_id=%s
' "$CI_JOB_ID"
    - printf 'sha=%s
' "$CI_COMMIT_SHA"
    - printf 'runner_id=%s
' "$CI_RUNNER_ID"
    - printf 'runner_description=%s
' "$CI_RUNNER_DESCRIPTION"
    - printf 'runner_tags=%s
' "$CI_RUNNER_TAGS"
    - printf 'runner_version=%s
' "$CI_RUNNER_VERSION"
    - printf 'runner_revision=%s
' "$CI_RUNNER_REVISION"
    - printf 'runner_arch=%s
' "$CI_RUNNER_EXECUTABLE_ARCH"
    - printf 'sha=%s
runner=%s
' "$CI_COMMIT_SHA" "$CI_RUNNER_ID" > runner-evidence.txt
  artifacts:
    expire_in: 1 day
    paths:
      - runner-evidence.txt

Because the tag is unique and “run untagged” is disabled, the expected job must match this runner’s routing policy. After execution, correlate pipeline/job/SHA and runner metadata; do not infer routing only from a green status.

6. Pause the runner and observe scheduling policy

Pause the disposable project runner in the GitLab UI. Do not stop the local manager yet. Trigger another trusted job on the same disposable branch. With no other runner carrying the unique ch04-lab tag, the job should remain pending because the runner configuration is deliberately ignoring new jobs.

Record the pending job ID and the runner’s paused state. Then resume the runner. The same queued job should become eligible without changing its YAML. This separates GitLab scheduling policy from repository configuration.

7. Stop the manager process and distinguish offline from paused

docker stop "$RUNNER_CONTAINER"
docker ps -a --filter "name=^/${RUNNER_CONTAINER}$"

The runner configuration still exists and is no longer paused, but the manager stops contacting GitLab and becomes offline after the normal status interval. Queue another uniquely tagged job and preserve its pending state. Then restart only the known container:

docker start "$RUNNER_CONTAINER"
docker logs --tail 80 "$RUNNER_CONTAINER"

When contact resumes, verify the pending job is claimed. The experiment proves that “unpaused” and “online manager” are separate conditions for execution.

8. Unregister the manager without confusing it with runner deletion

docker exec "$RUNNER_CONTAINER" gitlab-runner list

docker exec "$RUNNER_CONTAINER" \
  gitlab-runner unregister --name "$RUNNER_NAME"

docker exec "$RUNNER_CONTAINER" gitlab-runner list

With the modern authentication-token workflow, unregistering removes the manager registration/local configuration entry; the GitLab-side runner configuration can remain. Verify that distinction in the UI. Do not repeat registration merely to make the UI disappear.

9. Delete only the disposable runner configuration, then local storage

After confirming no useful jobs depend on the runner, remove the disposable runner configuration through the GitLab UI. Then remove only the exact local lab resources:

docker rm -f "$RUNNER_CONTAINER" 2>/dev/null || true

docker volume inspect "$RUNNER_VOLUME" >/dev/null 2>&1 && \
  docker volume rm "$RUNNER_VOLUME"

docker ps -a --filter "name=^/${RUNNER_CONTAINER}$"
docker volume ls --filter "name=^${RUNNER_VOLUME}$"

The final listing should show no lab container/volume. Keep non-secret evidence such as runner ID, manager system ID/version, pipeline/job IDs, and timestamps; do not retain the authentication token.

10. Challenge: classify state before changing it

Knowledge check

Official references and version notes

• Runners — runner categories, job scheduling, GitLab-hosted versus self-managed runners, and execution flow.
• Manage runners — project/group/instance scope, creation workflow, ownership and pause/resume operations.
• Configure runners — tags, run_untagged, protected runners, authentication-token rotation, and routing behavior.
• Registering runners and new runner creation workflow — current runner authentication-token registration and deprecated legacy registration-token behavior.
• GitLab Runner commands — register, list, verify, run, stop, and unregister lifecycle commands.
• Runner fleet planning — manager system_id identity and modern unregister/delete distinctions.
• Runners API — runner details, managers, status, pause, job history, authentication-token reset, and deletion semantics.
• Security for self-managed runners — remote-code-execution trust, Shell executor risk, persistent-runner residue, isolation, and credential exposure.
• GitLab Runner documentation — current compatibility guidance recommends keeping Runner major.minor aligned with GitLab; GitLab.com users should keep self-managed runners current.