Fix Docker Image Organization Mismatch

Overview

When to Use This Skill

Primary Trigger: Docker workflow fails with GHCR push errors after repository org change

Specific Indicators:

1. Error message: could not parse reference: ghcr.io/{OldOrg}/{repo}:tag
2. Error message: unable to parse registry reference
3. Docker build succeeds but push to GHCR fails with authentication error
4. Repository was recently transferred to a new GitHub organization
5. GITHUB_TOKEN scope shows different org than IMAGE_NAME in workflow

Example Error:

[0000] ERROR could not determine source: errors occurred attempting to resolve 'ghcr.io/mvillmow/ProjectOdyssey:main':
  - docker: could not parse reference: ghcr.io/mvillmow/ProjectOdyssey:main
  - oci-registry: unable to parse registry reference="ghcr.io/mvillmow/ProjectOdyssey:main"

Problem Background

Why This Happens

When a repository is transferred to a new GitHub organization:

1. GitHub workflows automatically get a GITHUB\_TOKEN scoped to the new org
2. Hardcoded IMAGE\_NAME variables still reference the old org
3. Docker tries to push to ghcr.io/old-org/repo using a token for new-org
4. GHCR rejects the push due to permission mismatch

Key Constraint

Docker image names MUST be lowercase, but github.repository preserves the original repository name case (e.g., HomericIntelligence/ProjectOdyssey). This causes failures in tools that manually construct Docker image references.

Verified Workflow

1. Identify All Hardcoded Image Names

Search for hardcoded org references in Docker-related files:

# Find IMAGE\_NAME in workflows
grep -r "IMAGE\_NAME" .github/workflows/

# Find GHCR references in workflows
grep -r "ghcr.io" .github/workflows/

# Find in Justfile/Makefile
grep -r "REPO\_NAME\|IMAGE\_NAME" justfile Makefile 2>/dev/null

Files to check:

• .github/workflows/docker.yml
• .github/workflows/release.yml
• justfile or Makefile
• Any Docker Compose files

2. Update Workflow IMAGE_NAME

Fix Pattern: Replace hardcoded org with lowercase new org name

# .github/workflows/docker.yml
env:
  REGISTRY: ghcr.io
  # BEFORE (BROKEN):
  IMAGE\_NAME: oldorg/projectname

  # AFTER (FIXED):
  IMAGE\_NAME: neworg/projectname  # lowercase org name

Critical: Image name must be all lowercase for Docker/GHCR compatibility.

3. Update Release Workflow

If you have a separate release workflow, add IMAGE\_NAME env var at job level:

# .github/workflows/release.yml
jobs:
  publish-docker:
    runs-on: ubuntu-latest
    env:
      # Add this env var
      IMAGE\_NAME: neworg/projectname  # lowercase

    steps:
      - name: Build and push
        uses: docker/build-push-action@v6
        with:
          tags: |
            ghcr.io/${{ env.IMAGE\_NAME }}:${{ needs.validate-version.outputs.version }}
            ghcr.io/${{ env.IMAGE\_NAME }}:latest

Replace:

• ghcr.io/${{ github.repository }} → ghcr.io/${{ env.IMAGE\_NAME }}

4. Update Build System References

If using Justfile or Makefile:

# justfile
REGISTRY := "ghcr.io"
# BEFORE:
REPO\_NAME := "oldorg/oldreponame"

# AFTER:
REPO\_NAME := "neworg/projectname"  # lowercase

5. Run Pre-commit and Verify

# Run all linting
just pre-commit-all

# Check for remaining old org references
grep -r "oldorg/projectname\|oldorg/oldreponame" \
  --include="*.md" --include="*.yml" --include="*.toml" .

# Verify no hardcoded paths remain
grep -r "/home/olduser" --include="*.md" --include="*.py" --include="*.sh" .

6. Commit and Create PR

# Commit changes
git add .github/workflows/docker.yml \
        .github/workflows/release.yml \
        justfile

git commit -m "fix(ci): update IMAGE\_NAME for new organization

- Update IMAGE\_NAME from oldorg to neworg
- Fix GHCR push authentication failures
- Ensure lowercase image names for Docker compatibility

Fixes Docker Build workflow where GITHUB\_TOKEN scoped to
new org could not push to old org's GHCR.
"

# Create PR
gh pr create \
  --title "fix(ci): update Docker image org references" \
  --body "Fixes GHCR push failures after org transfer" \
  --label "ci-cd"

7. Verify Docker Build Success

After PR is merged:

# Check Docker workflow status
gh run list --workflow="Docker Build and Publish" --branch main --limit 1

# View details
gh run view <run-id>

# Verify images pushed correctly
gh run view <run-id> --log | grep "pushing manifest"

Failed Attempts

Results & Parameters

Successful Configuration

docker.yml:

env:
  REGISTRY: ghcr.io
  IMAGE\_NAME: homericintelligence/projectodyssey  # lowercase

release.yml:

jobs:
  publish-docker:
    env:
      IMAGE\_NAME: homericintelligence/projectodyssey  # lowercase
    steps:
      - name: Build and push
        with:
          tags: |
            ghcr.io/${{ env.IMAGE\_NAME }}:${{ version }}
            ghcr.io/${{ env.IMAGE\_NAME }}:latest

justfile:

REGISTRY := "ghcr.io"
REPO\_NAME := "homericintelligence/projectodyssey"

Verification Results

✅ All Docker jobs passed:

• build-and-push (production): 4m34s ✅
• build-and-push (runtime): 6m18s ✅
• build-and-push (ci): 3m41s ✅
• security-scan: 1m18s ✅
• test-images: 1m47s ✅

✅ Images successfully pushed:

• ghcr.io/homericintelligence/projectodyssey:main
• ghcr.io/homericintelligence/projectodyssey:main-ci
• ghcr.io/homericintelligence/projectodyssey:main-prod
• Plus SHA-tagged variants

Performance Impact

• No performance impact - purely configuration fix
• Build times remain the same
• Authentication now works correctly with GITHUB_TOKEN

Additional Context

Common Pitfall: Case Sensitivity

Docker image names must be lowercase, but GitHub variables preserve case:

• github.repository → HomericIntelligence/ProjectOdyssey (mixed case) ❌
• IMAGE\_NAME → homericintelligence/projectodyssey (lowercase) ✅

Related Issues

This fix also addresses:

1. SBOM generation failures (anchore/sbom-action uses image name)
2. Security scanning failures (Trivy uses image name)
3. Image testing failures (test-images job needs correct reference)

Scope of Changes

Typical files to update:

• .github/workflows/docker.yml (primary)
• .github/workflows/release.yml (if exists)
• justfile or Makefile (local builds)
• Documentation references to old GHCR URLs

Cross-Repository Applicability

This skill applies to any repository that:

1. Uses GitHub Actions to build Docker images
2. Pushes to GitHub Container Registry (GHCR)
3. Was transferred to a new organization
4. Has hardcoded IMAGE_NAME or REPO_NAME variables

Generic workflow pattern (adapt to your repo):

env:
  REGISTRY: ghcr.io
  IMAGE\_NAME: <new-org>/<repo-name>  # lowercase, update this line

Verified On

References

• GitHub Actions: GHCR Authentication
• Docker Image Naming Conventions
• GitHub: Transferring a Repository