feat(docker): add Docker image publishing to GHCR

[cdelgehier]

This implementation adds automated Docker image publishing to GitHub Container Registry (ghcr.io) on every release tag.

• I have read the contributing guidelines

• Add test cases to all the changes you introduce

• Run uv run poe all locally to ensure this change passes linter check and tests

• Manually test the changes:

  • Verify the feature/bug fix works as expected in real-world scenarios
  • Test edge cases and error conditions
  • Ensure backward compatibility is maintained
  • Document any manual testing steps performed

• Update the documentation for the changes

• Run uv run poe doc locally to ensure the documentation pages renders correctly

• Check and fix any broken links (internal or external) in the documentation

When running uv run poe doc, any broken internal documentation links will be reported in the console output like this:

INFO    -  Doc file 'config.md' contains a link 'commands/bump.md#-post_bump_hooks', but the doc 'commands/bump.md' does not contain an anchor '#-post_bump_hooks'.

The Docker image will be published at: ghcr.io/commitizen-tools/commitizen

Key features:

• Multi-stage Dockerfile using Python 3.13 slim and UV
• GitHub Actions workflow for automated publishing on v* tags
• Multi-architecture support (amd64, arm64)
• Multiple image tags (latest, version, major.minor, major, sha)
• Build attestation for supply chain security
• Documentation: new Docker tutorial and updates to existing CI guides

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.96%. Comparing base (5857050) to head (544c521).

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1820   +/-   ##
=======================================
  Coverage   97.96%   97.96%           
=======================================
  Files          60       60           
  Lines        2648     2648           
=======================================
  Hits         2594     2594           
  Misses         54       54           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[woile]

Hi there, thanks for the intention, but we already have a docker repository, would you mind sending a PR there? 🙏🏻

https://github.com/commitizen-tools/commitizen-docker-image

[cdelgehier]

Hi @woile !

Thanks for your response.
I understand you have the separate docker repository, but I'd like to explain why migrating to GHCR in this repo would be beneficial:

• Current Issues with the Separate Repo

  Docker Hub Rate Limiting:

  • Docker Hub has strict pull rate limits
  • This affects CI/CD users who pull the image frequently
  • GHCR has no such limitations for public repositories

  Version Drift:

  • The current cron-based approach can cause delays between PyPI release and Docker image availability
  • Users may pull an outdated Docker image while the new version is already on PyPI
  • This PR ensures atomic publishing: when a release tag is created, both PyPI and Docker images are
    published simultaneously

  Complexity:

  • The separate repo requires a compare-versions script to detect new versions
  • Requires managing Docker Hub credentials as secrets
  • GHCR uses GITHUB_TOKEN (automatic, no secrets to manage)

  The separate repo can remain as a fallback for users who prefer Docker Hub, but GHCR would be the
  up-to-date approach.

[woile]

We can always trigger the job from here towards there once a release happen using gh workflow run ...

If you update the commitizen-docker-image to release to github, I'll do the gh workflow run 👍🏻