Skip to content

Authenticate with a private registry

Give OCX credentials for a registry that needs a login, so that installs, pulls and pushes against it succeed.

OCX looks for credentials per registry, so different registries can use different credentials. It tries each method in order and the first one that succeeds wins:

  1. Environment variables
  2. Docker credentials

Environment variables

Set the OCX_AUTH_* variables for a registry:

Terminal window
export OCX_AUTH_docker_io_TYPE=bearer
export OCX_AUTH_docker_io_TOKEN="<token>"

The variables are:

If TYPE is omitted, USER and TOKEN together mean basic and TOKEN alone means bearer. USER alone is ignored. The environment variable reference lists every OCX_AUTH_* variable.

Docker credentials

If a Docker configuration is found, OCX uses the stored credentials. The configuration is typically at ~/.docker/config.json and managed via:

Terminal window
docker login "<registry>"

Set DOCKER_CONFIG to change the directory. OCX delegates to Docker’s credential helper, which reads it. A credential resolves from credHelpers[REGISTRY], then auths[REGISTRY], then credsStore. Any OCX_AUTH_* variable for the registry wins over all of them, and then OCX runs no credential helper for that registry.

Credential helper installed with OCX

A credential helper such as the Amazon ECR credential helper can itself be an OCX package. Add it to the project or global toolchain and put the toolchain’s launcher directory on PATH. OCX then finds the helper there like any other docker-credential-* program.

  • OCX asks a helper for a registry’s credentials at most once per run, before it starts installing anything from that registry.
  • The first install of the helper cannot use the helper. Pull it with OCX_AUTH_* variables, or from a registry that allows anonymous access. Until the helper is installed, OCX skips it, warns that it is not installed, and carries on without those credentials.
  • To keep a registry away from the helper altogether, set OCX_AUTH_<REGISTRY>_TYPE=anonymous, or give it a TOKEN.

Storing credentials

ocx login REGISTRY writes credentials to the same ~/.docker/config.json that docker login and oras login use. The three tools interoperate, so a credential written by any of them is readable by the others. ocx login keeps the permissions of an existing file and writes through a symlink to its target. A file that other users can already read stays readable, so check its mode once with ls -l. If OCX cannot keep the file’s owner or group, it writes the file in place, so both stay as they are. A file that does not exist yet is created readable by its owner only.

Storage tier (highest priority first):

  1. credHelpers[REGISTRY] in ~/.docker/config.json (per-registry helper)
  2. credsStore (global default helper)
  3. Plaintext auths[REGISTRY].auth (gated by --allow-insecure-store)

For headless CI without a native keychain daemon, pipe the token via --password-stdin and pass --allow-insecure-store to opt into the plaintext tier. OCX_AUTH_* environment variables still take precedence over any docker-config-stored credential at read time.

Terminal window
echo "test-token" | ocx login -u ci --password-stdin --allow-insecure-store "$DEMO_REGISTRY"
ocx logout "$DEMO_REGISTRY"

After ocx login, confirm the credential works by pulling a package from the private registry, for example ocx package pull registry.example.com/team/tool:1.0. The pull succeeds when the registry accepts the credential, and fails with a non-zero exit when it does not.

Remove credentials with ocx logout. Logout exits 0 when the registry was never logged in, so CI cleanup scripts are safe to run unconditionally. A credential that cannot be removed exits non-zero.