Pull runner images from a private registry

You need an installed host, and a username with a password or access token for the registry, such as a GitHub token that can read packages for ghcr.io.

The host reads only the auths section of a Docker config file, and ignores credsStore and credHelpers. Without other settings it reads $DOCKER_CONFIG/config.json, or ~/.docker/config.json for the user the service runs as. If that file already has literal auths for your registry, skip to Check that it pulls. Otherwise, as when your Docker config names a credsStore the way Docker Desktop's does, give the host a file of its own.

Write the credentials fileCopy Anchor Link

Write the credentials beside the host's configuration:

{
  "auths": {
    "ghcr.io": {
      "username": "<user>",
      "password": "<token>"
    }
  }
}

Key each entry by the registry's host, as it appears at the start of the image name. For Docker Hub, use https://index.docker.io/v1/. For an entry in another form, such as auth or identitytoken, see Registry credentials.

Save it as /etc/spotlight/registry.json for a host installed as root, or ~/.spotlight/registry.json for one installed as yourself, and make it readable only by its owner:

chmod 600 ~/.spotlight/registry.json

Point the host at the fileCopy Anchor Link

Add the file's full path to host.env:

SPOTLIGHT_REGISTRY_CONFIG=/etc/spotlight/registry.json

Then restart the host. After that, a change to the file needs no restart: the host reads the credentials again on every pull.

Reinstalling drops this line from host.env; add it back afterwards.

Check that it pullsCopy Anchor Link

Open Settings from the workspace menu, then Runners. If the host's Images reads <n> refused, hover over it for each refused image and its reason. If the reason says Image can't be pulled, check the entry's key and the token's access to the image.

If the reason reads Image can't be pulled. Error: read registry credentials or ends auth is not base64, correct the credentials file. If a pull fails but the host has a copy of the image, it runs the copy and logs could not pull the runner image, so it runs the copy it has.

RelatedCopy Anchor Link

• Run a line in your own runner image
• Registry credentials, in the host configuration reference.