Skip to content

configuration.md

Latest commit

 

History

History
84 lines (70 loc) · 3.43 KB

configuration.md

File metadata and controls

84 lines (70 loc) · 3.43 KB
Raw

Configuration reference

The README lists every key of .claude/git.json with its default. Two of those keys carry enough structure to deserve a worked example: layers, which decides what runs before a commit, and promoteSteps, which attaches project-specific work to a promotion.

Both are optional. A project that sets neither still gets working commands — no layers means only the lint gate runs, and no promotion steps means a promotion is just the PR.

Complete config files for three project shapes live in examples/.

Gate layers

layers is what makes gate selection diff-scoped: /git:ship runs only the layers a change actually touches, in the right order.

{
  "layers": [
    {
      "name": "core",
      "paths": ["packages/core/"],
      "buildsFirst": true,
      "build": "…", "typecheck": "…", "test": "…"
    },
    {
      "name": "api",
      "paths": ["apps/api/"],
      "typecheck": "…",
      "test": "…",
      "testChanged": "… --changed {base}",
      "forcesFullSuite": ["apps/api/migrations/"],
      "requiresService": { "envFile": "apps/api/.env", "urlVar": "DATABASE_URL", "defaultPort": 5432 },
      "streamOutput": true
    }
  ]
}
  • name — how the layer is named in gate output.
  • paths — the file prefixes that put this layer in scope for a change.
  • build / typecheck / test — the layer's gate commands, run in that order. Omit any you don't have.
  • buildsFirst — build this layer before every other layer's gates (a dependency the others consume).
  • testChanged — an incremental test form. {base} is substituted with the PR's base branch. Used unless something in scope forces the full suite.
  • forcesFullSuite — paths whose effect a --changed run would miss because they reach the tests from outside the import graph. These are also what /git:promote reports as high-risk deploy paths.
  • requiresService — probes host:port before running the layer's tests; unreachable ⇒ the tests are skipped with a note rather than failed. Reads the address out of one of the project's own .env files. Reachability only — no credential is ever read into output.
  • streamOutput — tee this layer's test output live, for a long suite.

Layers are never inferred. Guessing a project's build and test commands would silently run the wrong thing, so an unconfigured project gets no layer gates at all.

Project-specific promotion steps

Some projects do real work as part of a promotion that no generic plugin can know about. Attach it without forking the command:

{
  "promoteSteps": {
    "beforePr": [
      { "name": "release artifact", "run": "…", "optional": true, "notes": "Skip if credentials are absent." }
    ],
    "afterPr": [
      { "name": "team announcement", "notes": "Draft a short announcement of the user-facing items." }
    ]
  }
}
  • name — how the step is named in the promotion report.
  • run — the command to execute. Omit it for an instruction-only step the model performs.
  • optional — true means a failure is reported and the promotion continues.
  • notes — free text, echoed verbatim into the report.

Permissions

Every command named in these two keys has to be allowlisted in your own project before the plugin may run it. The README explains why and what to paste in: Permissions — the one step you do yourself.