Authentication and CI

Use depot login and depot packages configure for local development. In CI, use an existing Depot job or runner token when available, publish with trusted publishing, or supply an explicit credential from your CI secret store.

Package managers must authenticate to read metadata, download packages, and publish. A repository that caches a public upstream still requires Depot authentication. Service discovery and signed download URLs don't require a second login.

Set up local development

1. Install the Depot CLI and sign in:

   depot login

   Copy code

2. Configure your package manager for a repository. This example routes npm through the built-in npmjs cache:

   depot packages configure npm --org <org-id> --repository npmjs

   Copy code

3. Run the package manager normally.

To configure a client by hand instead, follow the native configuration in your client guide. The guides use native client configuration and environment variables. No Depot package-manager adapter is required.

Configuration containing only repository URLs and environment-variable references can be shared. Don't commit credential files or URLs containing tokens. Environment variables are available to child processes; run unset DEPOT_TOKEN when finished.

Configure a package manager with the Depot CLI

depot packages configure <client> writes the routing and credential settings for one client and repository. It supports npm, pnpm, yarn (Yarn Classic only), bun, cargo, bundler, gem, helm, mamba, micromamba, pixi, apt, dnf, yum, zypper, and apk.

depot packages configure <client> --org <org-id> --repository <repository>

--org defaults to your current organization. The command uses DEPOT_TOKEN when it's set. Otherwise, it uses the token from depot login.

pnpm and Cargo get the current token from the Depot CLI each time they need it, so you don't have to rerun the command when your token changes. Cargo 1.79 or later is required. To save a token in their configuration instead, add --auth store.

All other clients save a copy of the token in their own configuration files. Only the file owner can read those files. Rerun the command when your token changes.

The command changes only Depot entries and keeps your other settings. It stops with an error, instead of reporting success, when an environment variable or project configuration file would override the new settings. Remove that setting, then rerun the command. The output lists every file it changed.

Route the default public registry through Depot

--replace-upstream routes the client's default public source through the repository. It applies to Cargo (crates.io), Bundler and gem (RubyGems.org), and mamba, micromamba, and Pixi (conda-forge and defaults channels). It's on by default when the repository is that registry's built-in cache, such as crates-io or rubygems. Use it only with a Cache or Virtual repository that includes the upstream registry.

To undo an earlier replacement, rerun the command with --replace-upstream=false.

Configure system package managers

apt, dnf, yum, zypper, and apk are supported on Linux only. The command writes files under /etc, or /root/.netrc for apk. Run it as root, or as a user who can use sudo or doas. It passes file contents to sudo or doas on standard input, so the token doesn't appear in the process list. It uses your Depot token, not the root user's login.

Each client guide lists the options for that client.

Understand permissions

The following permissions apply across repositories in the token's organization:

A repository must also support publishing. Cache repositories are read-only. For a Virtual repository, select a Private source in Publish packages to under Settings, Sources and publishing.

An organization token grants administrative access to all package repositories in that organization. Don't create one as the default way to install packages. A helper doesn't make an organization token narrower.

Use Depot CI and runners

Depot CI supplies a DEPOT_TOKEN to jobs. Keep that credential when configuring Packages; don't replace it with a personal or organization token. On Depot runners, use the existing runner credential when it's available to the process. Package-manager routing still needs configuration.

Follow the routing and authentication configuration in your client guide, then run its install or publish command. Use the injected DEPOT_TOKEN directly. If a client requires a credential file, create it inside the job with restricted permissions and exclude it from caches and artifacts.

Depot CI job tokens can publish by default. Untrusted pull request jobs are read-only. An explicit no-write job policy also prevents publishing. The registry recognizes allowPackageWrites; when it's absent, it uses allowArtifactWrites. These are job security policy fields, not a per-repository list of approved release workflows. Runner tokens have write permission, so keep them out of untrusted workloads.

Use external CI

Store a Depot credential with access to the target organization in your CI provider's secret store and expose it as DEPOT_TOKEN only to steps that need Packages. Then apply the native configuration in your client guide and run the install command.

Choose the credential's identity and permissions deliberately. A user token follows that user's organization membership. An organization token has administrative permissions. A GitHub GITHUB_TOKEN is not a Depot package credential. Avoid exposing publish credentials to untrusted pull request code.

For a publish step, use a Private repository or a Virtual repository with publishing enabled, and run the publish command from your ecosystem guide.

Publish without a stored token

To publish from GitHub Actions, GitLab CI/CD, or another CI system that issues OpenID Connect (OIDC) ID tokens, add a trust policy to the Private repository. The job then exchanges its ID token for a Depot token that expires after 15 minutes, so you don't store a publish credential in CI. The token can publish only to Private repositories whose trust policies match the ID token, and it doesn't work through a Virtual repository. See trusted publishing.

Use environment variables

When a tool supports environment-based credentials, you can obtain your stored personal token without copying it from the dashboard:

export DEPOT_TOKEN="$(depot login token)"

This exports a token to your shell and child processes. It doesn't configure a package manager. Follow the environment-variable alternative in its guide, then run unset DEPOT_TOKEN when finished. In CI, preserve the injected credential instead of replacing it with a local login. Check client credential precedence and remove stale saved entries when switching methods.

APT, RPM clients, apk, mamba, and Pixi can require credentials in local files. Their guides identify those files and explain when to refresh them.