Skip to main content
Root’s registries require authentication. This page covers credential setup for both cr.root.io (Root Image Catalog) and pkg.root.io (Root Library Catalog), including CI/CD and service account configurations.

​
Getting Credentials

Access to Root’s registries is provisioned during onboarding. You’ll receive:
  • A username (rootio for package registries, or your organization’s identifier)
  • A registry token - used as the password for all Root registries
Your token authenticates to both cr.root.io and pkg.root.io. Tokens are long-lived by default and can be rotated from the Root platform. To request access, contact Root.

​
Authenticating to cr.root.io

Docker CLI: 
docker login cr.root.io \
  --username rootio \
  --password YOUR_ROOT_TOKEN
After logging in, Docker stores credentials in ~/.docker/config.json. All subsequent docker pull cr.root.io/... commands use these credentials automatically. containerd credential helper: For containerd (used by Kubernetes nodes), configure credentials in /etc/containerd/config.toml: 
[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.configs."cr.root.io".auth]
    username = "rootio"
    password = "YOUR_ROOT_TOKEN"
Restart containerd after making changes: 
sudo systemctl restart containerd
Kubernetes ImagePullSecrets: 
kubectl create secret docker-registry root-registry-credentials \
  --docker-server=cr.root.io \
  --docker-username=rootio \
  --docker-password=YOUR_ROOT_TOKEN \
  --namespace=your-namespace
Reference the secret in your Pod spec: 
spec:
  imagePullSecrets:
    - name: root-registry-credentials
  containers:
    - name: app
      image: cr.root.io/python:3.12-slim
To apply credentials cluster-wide, add the secret to the default ServiceAccount in each namespace.

​
Authenticating to pkg.root.io

Each package manager uses its own configuration format. The token is the same across all ecosystems. pip / uv: 
# ~/.netrc
machine pkg.root.io
  login rootio
  password YOUR_ROOT_TOKEN
npm: 
npm config set //pkg.root.io/npm/:_authToken YOUR_ROOT_TOKEN --location=project
Maven (~/.m2/settings.xml): 
<servers>
  <server>
    <id>root-io</id>
    <username>rootio</username>
    <password>${env.ROOT_TOKEN}</password>
  </server>
</servers>
See the individual integration guides for full setup instructions: pip, npm, Maven, Yarn, pnpm, Poetry, uv.

​
Service Accounts for CI/CD

For CI/CD pipelines, store your Root token as a secret rather than hardcoding it. Recommended environment variable name: ROOT_TOKEN GitHub Actions: 
- name: Log in to Root Image Catalog
  uses: docker/login-action@v3
  with:
    registry: cr.root.io
    username: rootio
    password: ${{ secrets.ROOT_TOKEN }}
GitLab CI: 
before_script:
  - docker login cr.root.io --username rootio --password "$ROOT_TOKEN"
Generic shell: 
echo "$ROOT_TOKEN" | docker login cr.root.io --username rootio --password-stdin

​
Rotating Credentials

To rotate your registry token, generate a new one from the Root platform and update it in:
  1. Your CI/CD secret store (ROOT_TOKEN secret)
  2. Any ~/.netrc, .npmrc, or settings.xml files with the old token
  3. Kubernetes ImagePullSecrets: delete and recreate with the new token
# Re-create the Kubernetes ImagePullSecret after rotation
kubectl delete secret root-registry-credentials -n your-namespace
kubectl create secret docker-registry root-registry-credentials \
  --docker-server=cr.root.io \
  --docker-username=rootio \
  --docker-password=NEW_ROOT_TOKEN \
  --namespace=your-namespace
Tokens can be rotated without downtime - old tokens remain valid for a short grace period after a new token is issued.