Skip to main content
Check Image supports multiple methods for authenticating with private container registries. Credentials can be provided via CLI flags, environment variables, or Docker’s credential system.

​
Credential Precedence

When multiple credential sources are available, Check Image follows this priority order:
1

CLI Flags (Highest Priority)

Credentials provided via --username, --password, or --password-stdin flags.
2

Environment Variables

Credentials set in CHECK_IMAGE_USERNAME and CHECK_IMAGE_PASSWORD environment variables.
3

Docker Config (Lowest Priority)

Credentials from ~/.docker/config.json and Docker credential helpers.
The same credentials are applied to all registry requests in a single invocation. For per-registry credentials, use Docker credential helpers.

​
Authentication Methods

​
CLI Flags

Provide credentials directly on the command line using flags. 
check-image size my-registry.example.com/private-image:latest \
  --username myuser \
  --password mypassword
Security Risk: The --password flag makes your password visible in the process list. Use --password-stdin or environment variables instead.

​
Flag Details

​
--username
string
Registry username for authentication. Can also be set via CHECK_IMAGE_USERNAME environment variable.
​
--password
string
Registry password or token for authentication. Can also be set via CHECK_IMAGE_PASSWORD environment variable.
Visible in process list. Prefer --password-stdin or environment variables.
​
--password-stdin
boolean
Read registry password from stdin. Cannot be combined with other flags that also read from stdin (--config -, --allowed-ports @-, etc.).

​
Environment Variables

Set credentials via environment variables for use in scripts and CI/CD pipelines. 
export CHECK_IMAGE_USERNAME=myuser
export CHECK_IMAGE_PASSWORD=mypassword
check-image healthcheck my-registry.example.com/private-image:latest
Environment variables are ideal for CI/CD pipelines where credentials are stored as secrets.

​
Docker Config File

Check Image automatically uses credentials from Docker’s configuration file and credential helpers. 
docker login my-registry.example.com
check-image secrets my-registry.example.com/private-image:latest
This method requires no additional flags or environment variables. Check Image uses the authn.DefaultKeychain from go-containerregistry, which reads ~/.docker/config.json and invokes credential helpers automatically.

​
Registry-Specific Examples

​
GitHub Container Registry (GHCR)

GitHub Container Registry requires a Personal Access Token (PAT) with the read:packages scope. 
echo "$GITHUB_TOKEN" | check-image age ghcr.io/myorg/app:latest \
  --username myusername \
  --password-stdin
For GitHub Actions workflows, use the GITHUB_TOKEN secret which is automatically available.

​
Docker Hub

Docker Hub private repositories require a Docker Hub username and password or access token. 
check-image age docker.io/myorg/private-app:latest \
  --username mydockerhubuser \
  --password-stdin < ~/.docker-token

​
Amazon ECR

Amazon ECR requires an authorization token obtained via the AWS CLI. 
aws ecr get-login-password --region us-east-1 | \
  docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

check-image age 123456789012.dkr.ecr.us-east-1.amazonaws.com/my-app:latest

​
Google Container Registry (GCR)

GCR requires a service account key or OAuth token. 
cat key.json | docker login -u _json_key --password-stdin gcr.io
check-image age gcr.io/my-project/my-app:latest

​
Azure Container Registry (ACR)

ACR requires Azure credentials. 
az acr login --name myregistry
check-image age myregistry.azurecr.io/my-app:latest

​
Validation Rules

Check Image enforces several validation rules for credentials:
--password and --password-stdin are mutually exclusive. You cannot use both in the same command.
Error
check-image age nginx:latest --username user --password pass --password-stdin
# Error: --password and --password-stdin are mutually exclusive
If you provide a password (via any method), you must also provide a username.
Error
export CHECK_IMAGE_PASSWORD=mytoken
check-image age ghcr.io/myorg/app:latest
# Error: registry username required when password is set
If you provide a username (via any method), you must also provide a password.
Error
check-image age ghcr.io/myorg/app:latest --username myuser
# Error: registry password required when username is set
--password-stdin cannot be combined with other flags that read from stdin (--config -, --allowed-ports @-, --registry-policy -, etc.).
Error
cat config.json | check-image all nginx:latest --config - --password-stdin
# Error: multiple flags attempting to read from stdin

​
Security Best Practices

Use --password-stdin

Avoid putting passwords in command-line arguments. Use --password-stdin or environment variables.

Store secrets securely

Use secret management systems (GitHub Secrets, AWS Secrets Manager, HashiCorp Vault) in CI/CD pipelines.

Use credential helpers

Configure Docker credential helpers for automatic per-registry authentication.

Rotate tokens regularly

Use time-limited access tokens instead of long-lived passwords, and rotate them regularly.

​
Troubleshooting

Problem: Check Image cannot authenticate even though docker pull works.Solution: Ensure the Docker credential helper is correctly configured in ~/.docker/config.json. Check Image uses the same credential system as Docker.
Verify credentials
cat ~/.docker/config.json
docker login my-registry.example.com
Problem: Environment variables are set but authentication still fails.Solution: Verify both CHECK_IMAGE_USERNAME and CHECK_IMAGE_PASSWORD are set. Missing one will cause an error.
Check variables
echo $CHECK_IMAGE_USERNAME
echo $CHECK_IMAGE_PASSWORD
Problem: Password is visible when running ps aux.Solution: Use --password-stdin instead of --password to read the password from stdin.
Secure approach
echo "$PASSWORD" | check-image age image:latest --username user --password-stdin
Problem: Pulling from Docker Hub returns rate limit errors.Solution: Authenticate with your Docker Hub account to get higher rate limits.
Authenticate
docker login
check-image age nginx:latest

Image Reference Syntax

Learn about transport prefixes and image references

Configuration Files

Understand policy and configuration file formats

GitHub Action

Use Check Image in GitHub Actions workflows

CI/CD Integration

Integrate Check Image into your CI/CD pipeline

Build docs developers (and LLMs) love

Get started for freeTalk to us