at-container-registry/docs/DISTRIBUTION.md

Distribution Strategy for ATCR Credential Helper

Overview

The ATCR credential helper is distributed as pre-built binaries for all major platforms using GoReleaser and GitHub Actions. This document outlines the complete distribution pipeline.

Why Go is Ideal for Credential Helpers

Go is actually the perfect choice for Docker credential helpers:

1. Cross-compilation - Single command builds for all platforms
2. Static binaries - No runtime dependencies (unlike Node.js, Python, Ruby)
3. Industry standard - Most Docker credential helpers are written in Go:
   • docker-credential-helpers (official)
   • docker-credential-gcr (Google)
   • docker-credential-ecr-login (AWS)
   • docker-credential-pass (community)

Supported Platforms

Platform	Arch	Format	Status
Linux	amd64	tar.gz	✅
Linux	arm64	tar.gz	✅
macOS	amd64 (Intel)	tar.gz	✅
macOS	arm64 (Apple Silicon)	tar.gz	✅
Windows	amd64	zip	✅
Windows	arm64	zip	✅

Distribution Methods

1. GitHub Releases (Automated)

Trigger: Push a git tag (e.g., v1.0.0)

git tag v1.0.0
git push origin v1.0.0

What happens:

1. GitHub Actions runs (.github/workflows/release.yml)
2. GoReleaser builds binaries for all platforms
3. Creates GitHub release with:
   • Pre-built binaries (tar.gz/zip)
   • Checksums file
   • Changelog
4. Updates Homebrew tap (if configured)

Workflow file: .github/workflows/release.yml Config file: .goreleaser.yaml

2. Install Scripts

Linux/macOS: install.sh

• Detects OS and architecture
• Downloads latest release from GitHub
• Installs to /usr/local/bin (or custom dir)
• Makes executable and verifies installation

Windows: install.ps1

• Detects architecture
• Downloads latest release
• Installs to C:\Program Files\ATCR (or custom dir)
• Adds to system PATH
• Requires Administrator privileges

Usage:

# Linux/macOS
curl -fsSL https://atcr.io/install.sh | bash

# Windows (PowerShell)
iwr -useb https://atcr.io/install.ps1 | iex

3. Homebrew (macOS)

Setup required:

1. Create atcr-io/homebrew-tap repository
2. Set HOMEBREW_TAP_TOKEN secret in GitHub Actions
3. GoReleaser automatically updates formula on release

Usage:

brew tap atcr-io/tap
brew install docker-credential-atcr

Benefits:

• Automatic updates via brew upgrade
• Handles PATH configuration
• Native macOS experience

4. Manual Download

Users can download directly from GitHub Releases:

# Example: Linux amd64
VERSION=v1.0.0
curl -LO https://github.com/atcr-io/atcr/releases/download/${VERSION}/docker-credential-atcr_${VERSION#v}_Linux_x86_64.tar.gz
tar -xzf docker-credential-atcr_${VERSION#v}_Linux_x86_64.tar.gz
sudo install -m 755 docker-credential-atcr /usr/local/bin/

5. From Source

For users with Go installed:

go install atcr.io/cmd/credential-helper@latest
sudo mv $(go env GOPATH)/bin/credential-helper /usr/local/bin/docker-credential-atcr

Note: This requires Go 1.23+ and compiles locally.

Release Process

Creating a New Release

1. Update version (if using version consts anywhere)

2. Commit and tag:

   git add .
   git commit -m "Release v1.0.0"
   git tag -a v1.0.0 -m "Release v1.0.0"
   git push origin main
   git push origin v1.0.0
   

3. Wait for CI:

   • GitHub Actions builds and releases automatically
   • Check: https://github.com/atcr-io/atcr/actions

4. Verify release:

   • Visit: https://github.com/atcr-io/atcr/releases
   • Test install script:

     ATCR_VERSION=v1.0.0 curl -fsSL https://atcr.io/install.sh | bash
     docker-credential-atcr version
     

Version Information

GoReleaser injects version info at build time:

var (
    version = "dev"       // Set to tag (e.g., "v1.0.0")
    commit  = "none"      // Set to git commit hash
    date    = "unknown"   // Set to build timestamp
)

Usage:

$ docker-credential-atcr version
docker-credential-atcr v1.0.0 (commit: abc123, built: 2025-01-15T10:30:00Z)

Distribution Configuration

GoReleaser Config (.goreleaser.yaml)

Key sections:

Builds:

• Binary name: docker-credential-atcr (Windows: .exe auto-added)
• Targets: Linux, macOS, Windows (amd64, arm64)
• CGO disabled for static binaries
• Ldflags inject version info

Archives:

• Format: tar.gz (Linux/macOS), zip (Windows)
• Naming: docker-credential-atcr_VERSION_OS_ARCH.tar.gz
• Includes: LICENSE, README, INSTALLATION.md

Homebrew:

• Auto-updates tap repository
• Formula includes version check
• Installs to Homebrew prefix

Changelog:

• Auto-generated from commits
• Filters out docs/test/chore commits

Docker and Docker Desktop

How Docker Finds Credential Helpers

Docker looks for binaries named docker-credential-* in PATH:

1. User types: docker push atcr.io/alice/app:latest
2. Docker reads ~/.docker/config.json:

   {
     "credHelpers": {
       "atcr.io": "atcr"
     }
   }
   

3. Docker looks for docker-credential-atcr in PATH
4. Calls: docker-credential-atcr get (with atcr.io on stdin)
5. Helper returns credentials (JSON on stdout)

PATH Requirements

Linux/macOS:

• Common locations: /usr/local/bin, /usr/bin, $HOME/.local/bin
• Check with: which docker-credential-atcr

Windows:

• Common locations: C:\Windows\System32, C:\Program Files\ATCR
• Check with: where docker-credential-atcr

CI/CD Secrets

Required GitHub Secrets

1. GITHUB_TOKEN (automatic)

   • Provided by GitHub Actions
   • Used to create releases

2. HOMEBREW_TAP_TOKEN (manual setup)

   • Personal access token with repo scope
   • Used to update Homebrew tap
   • Can skip if not using Homebrew

Setup Instructions

# Create PAT with repo scope at:
# https://github.com/settings/tokens

# Add to repository secrets:
# https://github.com/atcr-io/atcr/settings/secrets/actions

Testing the Distribution

Before Tagging a Release

1. Test GoReleaser locally:

   goreleaser build --snapshot --clean
   ls dist/
   

2. Test specific platform:

   goreleaser build --snapshot --clean --single-target
   ./dist/docker-credential-atcr_*/docker-credential-atcr version
   

3. Test full release (dry run):

   goreleaser release --snapshot --clean --skip=publish
   

After Release

1. Test install script:

   # Clean install in fresh environment
   docker run --rm -it ubuntu:latest bash
   apt update && apt install -y curl
   curl -fsSL https://atcr.io/install.sh | bash
   

2. Test Docker integration:

   echo '{"credHelpers":{"atcr.io":"atcr"}}' > ~/.docker/config.json
   docker push atcr.io/test/image:latest
   

Future Enhancements

Package Managers

Linux:

• .deb packages for Debian/Ubuntu (via GoReleaser)
• .rpm packages for RHEL/Fedora/CentOS
• AUR package for Arch Linux

macOS:

• Official Homebrew core (requires popularity/maturity)

Windows:

• Chocolatey package
• Scoop manifest
• Winget package

Docker Distribution

Could also distribute the credential helper via container:

docker run --rm atcr.io/credential-helper:latest version

# Install from container
docker run --rm -v /usr/local/bin:/install \
  atcr.io/credential-helper:latest \
  cp /usr/local/bin/docker-credential-atcr /install/

Note: Not recommended as primary method (users want native binaries), but useful for CI/CD pipelines.

Troubleshooting

"Binary not in PATH"

Symptom: docker push fails with "credential helper not found"

Solution:

# Check if installed
which docker-credential-atcr
# or on Windows:
where docker-credential-atcr

# If not in PATH, add install dir to PATH
export PATH="/usr/local/bin:$PATH"  # Linux/macOS
# or add to ~/.bashrc, ~/.zshrc

"Permission denied"

Symptom: Can't execute binary

Solution:

chmod +x /usr/local/bin/docker-credential-atcr

"Wrong architecture"

Symptom: exec format error or bad CPU type

Solution: Download correct architecture:

• x86_64/amd64 for Intel/AMD
• arm64/aarch64 for Apple Silicon, ARM servers

Check with:

uname -m

Documentation

• User installation: INSTALLATION.md
• Project docs: CLAUDE.md
• README: README.md

References

• Docker Credential Helpers Spec
• GoReleaser Documentation
• GitHub Actions: Publishing