Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.root.io/llms.txt

Use this file to discover all available pages before exploring further.

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.