Skip to main content

atmos aws ecr login

Login to AWS Elastic Container Registry (ECR) using a named integration, an identity's linked integrations, or explicit registry URLs. Supports both private ECR (aws/ecr) and ECR Public (aws/ecr-public) registries. This command writes Docker credentials to the standard Docker config location.

atmos aws ecr login --help

Usage​

atmos aws ecr login [integration] [flags]

Examples​

# Login using a named integration (private ECR)
atmos aws ecr login dev/ecr/primary

# Login to ECR Public (public.ecr.aws) using ambient AWS credentials
atmos aws ecr login --public

# Login to ECR Public using a specific identity
atmos aws ecr login --public --identity dev-admin

# Login using an identity's linked integrations
atmos aws ecr login --identity dev-admin

# Pick an identity interactively (requires a TTY)
atmos aws ecr login --identity

# Login with explicit registry URL (uses current AWS credentials)
atmos aws ecr login --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com

# Login to multiple explicit registries
atmos aws ecr login \
  --registry 123456789012.dkr.ecr.us-east-1.amazonaws.com \
  --registry 987654321098.dkr.ecr.us-west-2.amazonaws.com

Arguments​

integration

Name of the integration to use for ECR login. The integration must be configured in auth.integrations with kind: aws/ecr or kind: aws/ecr-public. When provided, Atmos authenticates the integration's linked identity and logs into the configured registry.

Flags​

--public

Log in to AWS ECR Public (public.ecr.aws) directly, without a named integration. By default this uses ambient AWS credentials (the AWS SDK default credential chain: environment variables, shared config/profile, SSO, IMDS/IRSA/ECS) — ideal for CI, where the runner already has credentials. Combine with --identity to use a specific Atmos identity's credentials instead. Authentication is always performed in us-east-1. Cannot be combined with an integration argument or --registry.

--identity (alias -i)

Identity name whose linked integrations should be executed. All aws/ecr and aws/ecr-public integrations that reference this identity will be triggered. This authenticates the identity first, then executes all its linked integrations. When combined with --public, the identity's credentials are used to log in to ECR Public.

Passing --identity without a value opens an interactive picker to choose an identity (the same selector used by atmos auth login). This requires an interactive terminal (TTY); in CI or other non-interactive contexts it errors instead of prompting, so pass an explicit name there (--identity <name>).

--registry (alias -r)

Explicit ECR registry URL(s) for ad-hoc login. This mode uses the current AWS credentials from the environment (not Atmos identities). Can be specified multiple times for multiple registries.

Format: {account_id}.dkr.ecr.{region}.amazonaws.com

Configuration​

ECR integrations are configured in atmos.yaml under auth.integrations:

auth:
  providers:
    company-sso:
      kind: aws/iam-identity-center
      region: us-east-1
      start_url: https://company.awsapps.com/start/

  identities:
    dev-admin:
      kind: aws/permission-set
      via:
        provider: company-sso
      principal:
        name: AdministratorAccess
        account: dev

  # Integrations derive credentials from identities
  integrations:
    dev/ecr/primary:
      kind: aws/ecr
      via:
        identity: dev-admin           # Which identity provides AWS credentials
      spec:
        auto_provision: true          # Auto-trigger on identity login (default: true)
        registry:
          account_id: "123456789012"
          region: us-east-2

    dev/ecr/secondary:
      kind: aws/ecr
      via:
        identity: dev-admin
      spec:
        registry:
          account_id: "123456789012"
          region: us-west-2

ECR Public Configuration​

For a one-off ECR Public login, you don't need any configuration — just run atmos aws ecr login --public, which uses ambient AWS credentials (or pass --identity <name> to use a specific identity). This is the simplest option for CI.

To have ECR Public login happen automatically on atmos auth login, configure an aws/ecr-public integration kind. No registry block is needed since ECR Public is always public.ecr.aws:

auth:
  integrations:
    ecr-public:
      kind: aws/ecr-public
      via:
        identity: dev-admin
      spec:
        auto_provision: true

Integration Configuration Options​

aws/ecr (Private ECR)​

FieldRequiredDefaultDescription
kindYes-Must be aws/ecr for private ECR integrations
via.identityYes-Name of identity providing AWS credentials
spec.auto_provisionNotrueAuto-trigger on identity login
spec.registry.account_idYes-AWS account ID for the ECR registry
spec.registry.regionYes-AWS region for the ECR registry

aws/ecr-public (ECR Public)​

FieldRequiredDefaultDescription
kindYes-Must be aws/ecr-public for ECR Public integrations
via.identityYes-Name of identity providing AWS credentials
spec.auto_provisionNotrueAuto-trigger on identity login

ECR Public does not require a spec.registry block. The registry is always public.ecr.aws and authentication is always performed in us-east-1.

How It Works​

Named Integration Mode​

When you specify an integration name:

  1. Atmos looks up the integration config from auth.integrations
  2. Authenticates the linked identity (via via.identity)
  3. For aws/ecr: calls ecr:GetAuthorizationToken using the identity's credentials
  4. For aws/ecr-public: calls ecr-public:GetAuthorizationToken in us-east-1
  5. Writes credentials to Docker config (~/.docker/config.json)

Identity Mode​

When you use --identity:

  1. Atmos finds all integrations that reference the specified identity
  2. Authenticates the identity
  3. Executes each linked integration
  4. Each integration writes its credentials to Docker config

Explicit Registry Mode​

When you use --registry:

  1. Atmos uses the current AWS credentials from the environment
  2. Parses the registry URL to extract account ID and region
  3. Calls ecr:GetAuthorizationToken
  4. Writes credentials to Docker config (~/.docker/config.json)

Credential Storage​

ECR credentials are written to ~/.docker/config.json by default, the standard Docker config location. This means:

  • Docker commands work immediately after login without additional configuration
  • Credentials are merged with existing entries in your Docker config
  • Respects DOCKER_CONFIG environment variable if set

If you need isolated credentials, set DOCKER_CONFIG before running the command:

export DOCKER_CONFIG=~/.config/atmos/docker
atmos aws ecr login dev/ecr/primary

Auto-Provisioning​

When auto_provision is true (the default), ECR integrations are automatically triggered when you authenticate with their linked identity:

$ atmos auth login dev-admin
Authenticating with identity: dev-admin
Opening browser for SSO authentication...
Successfully authenticated as dev-admin
✓ ECR login: 123456789012.dkr.ecr.us-east-2.amazonaws.com (expires in 11h59m)
✓ ECR login: 123456789012.dkr.ecr.us-west-2.amazonaws.com (expires in 11h59m)

To disable auto-provisioning for an integration, set auto_provision: false:

integrations:
  dev/ecr/optional:
    kind: aws/ecr
    via:
      identity: dev-admin
    spec:
      auto_provision: false  # Only triggered via explicit `atmos aws ecr login` command
      registry:
        account_id: "123456789012"
        region: eu-west-1

Error Handling​

  • Named integration failures: Return error to user (fatal)
  • Auto-provisioned integration failures: Log warning and continue (non-fatal)
  • Invalid registry URL: Return error with supported format

ECR integration failures during atmos auth login are logged but don't block authentication. Your identity credentials succeed even if ECR login fails.

Notes​

  • ECR tokens expire after approximately 12 hours (AWS-enforced)
  • The actual expiration time is displayed when login succeeds
  • Private ECR (aws/ecr): requires ecr:GetAuthorizationToken IAM permission
  • ECR Public (aws/ecr-public): requires ecr-public:GetAuthorizationToken and sts:GetServiceBearerToken IAM permissions. Authentication is always performed in us-east-1. ECR Public is only available in us-east-1 and us-west-2.
  • China and GovCloud regions are not supported for either integration kind

See Also​