stiftung-management-system/GHCR_AUTH_SETUP.md

GitHub Container Registry Authentication Setup

Problem

The deployment pipeline fails to pull Docker images from GitHub Container Registry (GHCR) with error:

Error response from daemon: Head "https://ghcr.io/v2/remmerinio/stiftung-management-system/manifests/latest": denied: denied

Root Cause

The GITHUB_TOKEN used in GitHub Actions has limited permissions and cannot access private container packages.

Solution: Create Personal Access Token

1. Create GitHub Personal Access Token

1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Select these scopes:
   • ✅ read:packages - Download packages from GitHub Package Registry
   • ✅ write:packages - Upload packages to GitHub Package Registry
   • ✅ repo - Full control of private repositories (if repo is private)

2. Add Token to Repository Secrets

1. Go to your repository → Settings → Secrets and variables → Actions
2. Click "New repository secret"
3. Name: DEPLOY_TOKEN
4. Value: Your personal access token
5. Click "Add secret"

3. Verify Token Works

Test the token manually:

echo "YOUR_TOKEN_HERE" | docker login ghcr.io -u YOUR_USERNAME --password-stdin
docker pull ghcr.io/remmerinio/stiftung-management-system:latest

Alternative: Make Container Package Public

1. Go to GitHub → Your Profile → Packages
2. Find stiftung-management-system package
3. Click on it → Package settings
4. Change visibility to "Public"
5. No authentication needed for public packages

Deployment Script Improvements

The updated deployment script now:

• ✅ Uses DEPLOY_TOKEN instead of GITHUB_TOKEN
• ✅ Has fallback to local build if GHCR pull fails
• ✅ Provides clear error messages
• ✅ Continues deployment even if registry is unavailable