> ## 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.

# Registry Credentials

> How to authenticate to Root's registries for container images and application packages.

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](https://root.io).

## Authenticating to cr.root.io

**Docker CLI:**

```bash theme={null}
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`:

```toml theme={null}
[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:

```bash theme={null}
sudo systemctl restart containerd
```

**Kubernetes ImagePullSecrets:**

```bash theme={null}
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:

```yaml theme={null}
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:**

```bash theme={null}
# ~/.netrc
machine pkg.root.io
  login rootio
  password YOUR_ROOT_TOKEN
```

**npm:**

```bash theme={null}
npm config set //pkg.root.io/npm/:_authToken YOUR_ROOT_TOKEN --location=project
```

**Maven (`~/.m2/settings.xml`):**

```xml theme={null}
<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](/integrations/pip), [npm](/integrations/npm), [Maven](/integrations/maven), [Yarn](/integrations/yarn), [pnpm](/integrations/pnpm), [Poetry](/integrations/poetry), [uv](/integrations/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:**

```yaml theme={null}
- 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:**

```yaml theme={null}
before_script:
  - docker login cr.root.io --username rootio --password "$ROOT_TOKEN"
```

**Generic shell:**

```bash theme={null}
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

```bash theme={null}
# 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.