Watchtower Private Registry Authentication

How Watchtower Authenticates

Watchtower doesn't have its own credential store. Instead, it reads the standard Docker credential file — the same ~/.docker/config.json created when you run docker login. Mount it into the container at /config.json (read-only):

services:
  watchtower:
    image: nickfedor/watchtower:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /root/.docker/config.json:/config.json:ro
    environment:
      - WATCHTOWER_CLEANUP=true
      - WATCHTOWER_POLL_INTERVAL=86400
    restart: unless-stopped

Run docker login ghcr.io (or your registry) on the host first — Watchtower picks the credentials up automatically on its next check.

GitHub Container Registry (GHCR)

echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Use a fine-grained personal access token with read:packages scope — never your account password. The token lives in the host's config.json, which Watchtower reads read-only.

GitLab Container Registry

docker login registry.gitlab.com -u YOUR_USERNAME -p YOUR_DEPLOY_TOKEN

Prefer a deploy token scoped to the project over a personal token — it limits blast radius if the host is compromised.

Docker Hub Private Repos

docker login -u YOUR_USERNAME

Use an access token (Account Settings → Security), not your password — especially since Docker Hub rate-limits anonymous pulls.

Self-Hosted Registries

For registries with self-signed certificates, Watchtower needs the CA. Mount your CA bundle and point Docker at it on the host (/etc/docker/certs.d/); Watchtower inherits the host's trust through the daemon for pulls. Some forks also support an explicit registry CA bundle flag — check your fork's docs.

Troubleshooting Auth Failures