Skip to main content

Hook usage (consuming repositories)

How to add a2c-pre-commit-hooks to an A2C-governed software repository.

Prerequisites​

  • pre-commit installed (pip install pre-commit)

  • Root-level CHANGELOG.md (Keep a Changelog format)

  • Git hooks installed in the consuming repo:

    pre-commit install
    pre-commit install --hook-type merge-commit

Add the hook​

Create or extend .pre-commit-config.yaml at the repository root:

repos:
  - repo: https://gitlab.com/libesys/ai-workflows/a2c-pre-commit-hooks.git
    rev: v0.2.0
    hooks:
      - id: check-changelog
      - id: validate

Replace rev with the latest release tag.

The validate hook installs a2c-cli from PyPI (version pinned in pyproject.toml [project.optional-dependencies.validate], currently 0.2.1). Pre-commit pulls it via the .[validate] extra declared in .pre-commit-hooks.yaml — only when validate is enabled.

Override the CLI version in your .pre-commit-config.yaml when needed:

      - id: validate
        additional_dependencies:
          - a2c-cli==0.2.1

Or install the extra locally: pip install -e ".[validate]" in a clone of this repository.

SSH remotes​

If your environment uses GitLab SSH (git@gitlab-ai:...):

  - repo: git@gitlab-ai:libesys/ai-workflows/a2c-pre-commit-hooks.git
    rev: v0.2.0
    hooks:
      - id: check-changelog
      - id: validate

What check-changelog enforces​

When you run git commit (or merge-commit hooks):

Staged filesResult
(none)Pass
Only CHANGELOG.mdPass
CHANGELOG.md + other filesPass
Other files without CHANGELOG.mdFail
Other files, no CHANGELOG.md on diskFail (create changelog first)

The hook inspects the Git index (staged files), not unstaged working-tree edits.

Typical workflow​

  1. Make code or documentation changes.

  2. Update ## [Unreleased] in CHANGELOG.md for release-relevant work.

  3. Stage everything:

    git add src/my_module.py CHANGELOG.md
    git commit -m "feat(app): Add export endpoint"

  4. If you forget the changelog, the hook prints a message and blocks the commit.

Changelog-only commits​

Documentation or release prep that touches only the changelog is allowed:

git add CHANGELOG.md
git commit -m "docs(changelog): Curate unreleased notes"

What validate enforces​

When enabled, the hook runs a2c validate on the repository root (repo-wide, not per staged file). It checks A2C config, workflow manifest, planning epics/tasks/sprints, unique ids, and cross-references.

OutcomeHook result
Valid A2C repositoryPass
Validation errors in planning artifactsFail (exit 1)
Not inside an A2C repositoryFail (exit 2)

Use this hook only in A2C-governed repositories that already use the a2c CLI.

pre-commit run validate

Optional hook arguments​

      - id: check-changelog
        args: [--changelog-file, CHANGELOG.md]

Use a different path only when your project standard explicitly places the changelog elsewhere (A2C default is repository root CHANGELOG.md).

For validate:

      - id: validate
        args: [--repo-root, .]

Manual run​

Run on staged changes without committing:

pre-commit run check-changelog

Run against all files is not the default CI pattern for consuming repos; use normal commit-time hooks locally.

Updating the hook version​

  1. Check release tags.

  2. Bump rev in .pre-commit-config.yaml.

  3. Refresh cached environments:

    pre-commit autoupdate --repo https://gitlab.com/libesys/ai-workflows/a2c-pre-commit-hooks.git
    # or: pre-commit clean && pre-commit run check-changelog

Troubleshooting​

SymptomLikely cause
Hook not foundWrong rev or repo URL; verify tag exists
Fails despite editing changelogCHANGELOG.md edited but not staged (git add CHANGELOG.md)
SSL / clone errorsOn Windows run scripts/fix-git-ssl.ps1 from this repo (or the copy in your consuming repo if mirrored); use SSH repo URL for GitLab; see development.md
a2c-cli is not installedEnable validate in .pre-commit-config.yaml; run pre-commit clean after upgrading hook rev
Validate import / pip errorsPin a2c-cli==0.2.1 (or newer) under validate → additional_dependencies; ensure PyPI access
Windows path issuesHook normalizes paths; ensure changelog path uses forward slashes in config