repomatic

A Python CLI and pyproject.toml configuration that let you release Python packages multiple times a day with only 2-clicks. Designed for uv-based Python projects, but usable for other projects too. The CLI operates through reusable GitHub Actions workflows as its CI delivery mechanism.

Maintainer-in-the-loop: nothing is done behind your back. A PR or issue is created every time a change is proposed or action is needed.

Automates:

• Version bumping
• Changelog management
• Formatting autofix for: Python, Markdown, JSON, typos
• Linting: Python types with mypy, YAML, zsh, GitHub Actions, workflow security, URLS & redirects, Awesome lists, secrets
• Compiling of Python binaries for Linux / macOS / Windows on x86_64 & arm64
• Building of Python packages and upload to PyPI
• Produce attestations
• Git version tagging and GitHub release creation
• Synchronization of: uv.lock, .gitignore, .mailmap and Mermaid dependency graph
• Auto-locking of inactive closed issues
• Static image optimization
• Sphinx documentation building & deployment, and autodoc updates
• Label management, with file-based and content-based rules
• Awesome list template synchronization
• Address GitHub Actions limitations

Quick start

$ cd my-project
$ uvx -- repomatic init
$ git add . && git commit -m "Update repomatic files" && git push

This works for both new and existing repositories — managed files (workflows, configs, skills) are always regenerated to the latest version. The only exception is changelog.md, which is never overwritten once it exists. The workflows will start running and guide you through any remaining setup (like creating a REPOMATIC_PAT secret) via issues and PRs in your repository. After that, the autofix workflow handles ongoing sync.

Run repomatic init --help to see available components and options.

repomatic CLI

Try it

Thanks to uv, you can run it in one command, without installation or venv:

$ uvx -- repomatic
Usage: repomatic [OPTIONS] COMMAND [ARGS]...

Options:
  --time / --no-time      Measure and print elapsed execution time.  [default:
                          no-time]
  --color, --ansi / --no-color, --no-ansi
                          Strip out all colors and all ANSI codes from output.
                          [default: color]
  --config CONFIG_PATH    Location of the configuration file. Supports local
                          path with glob patterns or remote URL.  [default:
                          ~/Library/Application Support/repomatic/{*.toml,*.yaml
                          ,*.yml,*.json,*.ini,pyproject.toml}]
  --no-config             Ignore all configuration files and only use command
                          line parameters and environment variables.
  --validate-config FILE  Validate the configuration file and exit.
  --show-params           Show all CLI parameters, their provenance, defaults
                          and value, then exit.
  --table-format [aligned|asciidoc|colon-grid|csv|csv-excel|csv-excel-tab|csv-unix|double-grid|double-outline|fancy-grid|fancy-outline|github|grid|heavy-grid|heavy-outline|hjson|html|jira|json|json5|jsonc|latex|latex-booktabs|latex-longtable|latex-raw|mediawiki|mixed-grid|mixed-outline|moinmoin|orgtbl|outline|pipe|plain|presto|pretty|psql|rounded-grid|rounded-outline|rst|simple|simple-grid|simple-outline|textile|toml|tsv|unsafehtml|vertical|xml|yaml|youtrack]
                          Rendering style of tables.  [default: rounded-outline]
  --verbosity LEVEL       Either CRITICAL, ERROR, WARNING, INFO, DEBUG.
                          [default: WARNING]
  -v, --verbose           Increase the default WARNING verbosity by one level
                          for each additional repetition of the option.
                          [default: 0]
  --version               Show the version and exit.
  -h, --help              Show this message and exit.

Project setup:
  init                      Bootstrap a repository to use reusable workflows
  metadata                  Output project metadata
  show-config               Print [tool.repomatic] configuration reference
  workflow                  Lint downstream workflow caller files
  update-deps-graph         Generate dependency graph from uv lockfile
  update-docs               Regenerate Sphinx API docs and run update script
  list-skills               List available Claude Code skills
  update-checksums          Update SHA-256 checksums for binary downloads
  format-images             Format images with lossless optimization

Release & versioning:
  changelog                 Maintain a Markdown-formatted changelog
  release-prep              Prepare files for a release
  version-check             Check if a version bump is allowed
  git-tag                   Create and push a Git tag

Sync:
  sync-gitignore            Sync .gitignore from gitignore.io templates
  sync-github-releases      Sync GitHub release notes from changelog
  sync-dev-release          Sync rolling dev pre-release on GitHub
  sync-mailmap              Sync Git's .mailmap file with missing contributors
  fix-vulnerable-deps       Upgrade packages with known vulnerabilities
  sync-uv-lock              Re-lock dependencies and prune stale cooldown
                            overrides
  sync-bumpversion          Sync bumpversion config from bundled template
  clean-unmodified-configs  Remove config files that match bundled defaults
  sync-labels               Sync repository labels via labelmaker

Linting & checks:
  test-plan                 Run a test plan from a file against a binary
  verify-binary             Verify binary architecture using exiftool
  check-renovate            Check Renovate migration prerequisites
  lint-repo                 Run repository consistency checks
  lint-changelog            Check changelog dates against release dates
  run                       Run an external tool with managed config

GitHub issues & PRs:
  sponsor-label             Label issues/PRs from GitHub sponsors
  broken-links              Manage broken links issue lifecycle
  setup-guide               Manage setup guide issue lifecycle
  unsubscribe-threads       Unsubscribe from closed, inactive notification
                            threads
  pr-body                   Generate PR body with workflow metadata

$ uvx -- repomatic --version
repomatic, version 6.9.0

That's the best way to get started with repomatic and experiment with it.

Executables

To ease deployment, standalone executables of repomatic's latest version are available as direct downloads for several platforms and architectures:

| Platform | arm64 | x86_64 | | :---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Linux | Download repomatic-6.10.0-linux-arm64.bin | Download repomatic-6.10.0-linux-x64.bin | | macOS | Download repomatic-6.10.0-macos-arm64.bin | Download repomatic-6.10.0-macos-x64.bin | | Windows | Download repomatic-6.10.0-windows-arm64.exe | Download repomatic-6.10.0-windows-x64.exe |

That way you have a chance to try it out without installing Python or uv. Or embed it in your CI/CD pipelines running on minimal images. Or run it on old platforms without worrying about dependency hell.

[tool.repomatic] configuration

Downstream projects can customize workflow behavior by adding a [tool.repomatic] section in their pyproject.toml:

[tool.repomatic]
pypi-package-history = ["old-name", "older-name"]

awesome-template.sync = false
bumpversion.sync = false
dev-release.sync = false
gitignore.sync = false
labels.sync = false
mailmap.sync = false
setup-guide = false
uv-lock.sync = false

dependency-graph.output = "./docs/assets/dependencies.mmd"
dependency-graph.all-groups = true
dependency-graph.all-extras = true
dependency-graph.no-groups = []
dependency-graph.no-extras = []
dependency-graph.level = 0

gitignore.location = "./.g