ARC runner image "ImagePullBackOff" in CI

By Daniel Zoghalchali·Latchkey

The runner pod cannot pull its container image. Kubernetes reports ImagePullBackOff, so the runner never starts. The tag is wrong, the registry is private, or no image pull secret was provided.

What this error means

The runner pod stays in ImagePullBackOff or ErrImagePull, with an event showing a 401/403 or manifest not found for the runner or dind image.

Failed to pull image "ghcr.io/acme/runner:latest":
rpc error: code = Unknown desc = failed to authorize:
401 Unauthorized

Common causes

Private registry without an image pull secret

A custom runner image in a private registry needs imagePullSecrets on the runner pod; without it the pull is unauthenticated and fails.

Wrong image name or tag

A misspelled repository or a tag that does not exist yields a manifest-not-found error.

How to fix it

Add an image pull secret to the runner template

1. Create a docker-registry secret in the runner namespace.
2. Reference it via imagePullSecrets in the scale set values.
3. Reinstall the scale set and confirm the pull succeeds.

kubectl create secret docker-registry ghcr-pull \
  --namespace arc-runners \
  --docker-server=ghcr.io \
  --docker-username=<user> --docker-password=<token>

Set the image and pull secret in values

Point the runner container at the correct image and attach the pull secret.

template:
  spec:
    imagePullSecrets:
      - name: ghcr-pull
    containers:
      - name: runner
        image: ghcr.io/acme/runner:1.2.3

How to prevent it

• Use immutable tags, not latest, for custom runner images.
• Provision image pull secrets before deploying the scale set.
• Verify the image reference resolves from inside the cluster.

Frequently asked questions

Related guides

References

• GitHub Actions documentation