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:

Cross-compilation - Single command builds for all platforms
Static binaries - No runtime dependencies (unlike Node.js, Python, Ruby)
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:

GitHub Actions runs (.github/workflows/release.yml)
GoReleaser builds binaries for all platforms
Creates GitHub release with:
- Pre-built binaries (tar.gz/zip)
- Checksums file
- Changelog
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:

Create atcr-io/homebrew-tap repository
Set HOMEBREW_TAP_TOKEN secret in GitHub Actions
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#

Update version (if using version consts anywhere)

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

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

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:

User types: docker push atcr.io/alice/app:latest

Docker reads ~/.docker/config.json:

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

Docker looks for docker-credential-atcr in PATH
Calls: docker-credential-atcr get (with atcr.io on stdin)
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#

GITHUB_TOKEN (automatic)
- Provided by GitHub Actions
- Used to create releases
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#

Test GoReleaser locally:

goreleaser build --snapshot --clean
ls dist/

Test specific platform:

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

Test full release (dry run):

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

After Release#

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

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