Skip to content

Authentication

This guide walks through OCI registry authentication in margot: which commands need it, how to log in, how expiry is tracked, and how to rotate or remove credentials.

For the flag reference, see margot auth.

Which commands require authentication

  • margot push requires valid registry credentials. Pushing fails immediately if no credentials are present or if they have expired.
  • margot pull and margot fetch work anonymously — they never use stored credentials. Passing --username / --password-stdin is not supported by these commands.
  • margot build, margot verify, and margot describe are entirely local — no registry contact at all.

Logging in

Generic registry

margot auth login registry.example.com --username myuser --password-stdin

margot delegates the OCI auth challenge-response flow to oras-py. Credentials are stored in the configured credential store (same as Docker/Podman), so logins you've already done with Docker or Podman are visible to margot.

If you prefer not to pass the password via stdin, omitting --password-stdin prompts you interactively.

AWS ECR

ECR tokens are retrieved with the AWS CLI and piped directly into margot. The token acts as the password; --username AWS is the fixed username the ECR API requires.

# Public ECR (us-east-1 is the only supported region for public.ecr.aws)
aws ecr-public get-login-password --region us-east-1 \
  | margot auth login public.ecr.aws --username AWS --password-stdin

# Private ECR (replace us-east-1 with your registry region)
aws ecr get-login-password --region us-east-1 \
  | margot auth login 123456789012.dkr.ecr.us-east-1.amazonaws.com \
      --username AWS --password-stdin

Credential expiry lifecycle

What gets persisted and where

When margot detects an expiry from the token (ECR tokens carry their own expiry), it writes a timestamp to ~/.config/margot/credentials.toml:

[registries."public.ecr.aws"]
expires_at = "2026-06-27T01:00:00Z"

This happens automatically — no flag needed. --expiry-hours only exists to override the auto-detected value, or to supply one when the token itself carries no expiry. You do not need to pass --expiry-hours to enable expiry tracking with ECR.

What happens before each registry operation

Every command that contacts the registry (margot push) checks the credentials file first:

  • More than 1 hour remaining: proceeds normally.
  • Less than 1 hour remaining: prints a warning and proceeds. You can still push, but refreshing now avoids a failure mid-build later.
  • Expired: fails immediately with a message and a margot auth login hint. Nothing is pushed.

Checking status proactively

Before pushing — especially in a new session or after an overnight break — check your credential state:

margot auth status

This shows a table with expiry timestamps and current status (VALID, EXPIRING, EXPIRED, or UNKNOWN) for all tracked registries. Catching a near-expiry here is easier than diagnosing a mid-pipeline failure.

Registries logged in via Docker/Podman but without a margot-tracked expiry appear in the table with Status: UNKNOWN. They can still be used for pushing — margot just has no expiry information for them.

See margot auth for the full table format.

Logging out

margot auth logout public.ecr.aws

This removes the stored credentials from the credential store and deletes the expiry entry from ~/.config/margot/credentials.toml.