AI-generated commit message (requires API key configured in czg)

April 25, 2026 · View on GitHub

Hooks Setup And Usage

Pre-commit runs Biome checks on affected directories and schema validation tests where applicable.
Pre-push runs workspace tests and schema validation checks.
npm install also runs npm prepare, which configures the hooks path automatically. To skip hooks temporarily:

git commit --no-verify
git push --no-verify

This repository uses native Git hooks in .githooks/.

After cloning, activate the hooks by

OPTION 1 - Running Setup Script

# Make the setup script executable and run it
chmod +x .githooks/setup.sh
./.githooks/setup.sh

OPTION 2 - Manually Installation

# remove hooks path
git config --local --unset-all core.hooksPath

# set hooks path explicitly
git config --local core.hooksPath .githooks
chmod +x .githooks/pre-commit .githooks/pre-push

OPTION 3 - Via NPM prepare script

Running npm install will also run npm prepare, which configures the hooks path automatically.

pre-commit hook

Runs automatically on every git commit:

Check	Details
Biome format & lint	Runs `npx biome check` on each affected directory (`common/iso`, `common/node`, `common/vue`, `common/web`, `apps`, `scripts`). Run `npm run check` to auto-fix.
Schema validation tests	Runs `npm run test:schemas -- <folder>` for each affected schema directory (`common/schema`, `common/schemas`, `apps//schema`, `apps//schemas`).

To skip the pre-commit hook temporarily:

git commit --no-verify

pre-push hook

Runs automatically on every git push:

Check	Details
Unit tests	Runs `npm run test:workspaces` (or `npm test`).
Schema validation tests	Runs `npm run test:schemas` if the script exists.

To skip the pre-push hook temporarily:

git push --no-verify

Branching And Protection

Branch tags used

<feat/fix/chore>/scope/<...>
rel/
, rel/
- can add -rc.1, -beta.1 suffixes as needed
hotfix//<...>
tag/
main

Examples:

release branch: rel/1.1
patch tags: tag/1.1.1
beta release: rel/1.1-beta.4

Branch & Tag Summary & Flow

Use the table below to find out how to name branches based on action taken. Usually, contributors will create feat/fix/chore based off a rel branch

Branch	Branch from	Merge to	Notes
`rel/1.0`	`main`	`main` when production ready	Active dev branch
`feat/fix/chore`	`rel/1.0`	`rel/1.0` via PR	Day-to-day work
`hotfix/scope/name`	`main`	`main` + `rel/1.0` + `rel/2.0`	Emergency only
`tag: v1.0.0`	`rel/1.0` after merge to main	—	Full release tag
`tag: v1.0.1`	`rel/1.0` after hotfix merges in	—	Patch tag, then rel/1.0 → main
`rel/1.1`	`main` after `v1.0.0` tag	`main` when ready	Cut from stable tag

The consistent rule is: tags always come from rel/*, never directly from main. Main is the destination, not the source of truth for what shipped.

Hotfix & Backport Flow

hotfix/payment-crash (check out from main)
  → merge to main (keeps main stable)
  → merge to rel/1.0
      → tag v1.0.1 here (patch tag on rel/1.0)
      → DO NOT DO THIS! DANGEROUS! merge rel/1.0 to main (main now has the patch)
  → cherry-pick to rel/2.0 (backport)

Branch Protection Rules

Edit branch protection rules in Settings → Branches → Add branch protection rule to prevent merges when CI checks fail.

Match the following patterns:

Pattern: main
Pattern: rel/*

For each pattern, enable:

Setting	Action
Require a pull request before merging	Enable. Require 1 approval. Dismiss stale approvals on new commits.
Require status checks to pass	Enable. Require branches to be up to date.
	Add required checks: `Commit Message Format`, `Biome Checks`, `Schema Validation Tests`, `Unit Tests`, `Integration Tests`, `E2E Tests`
Require conversation resolution before merging	Enable.
Include administrators	Enable. Prevents bypass by repo admins.

Commit Message

For standardized Conventional Commits messages, use czg instead of git commit -m "…":

# Interactive prompt (guided commit message)
npx czg

# AI-generated commit message (requires API key configured in czg)
npx czg --ai

Install globally for convenience:

npm install -g czg

Use the repository commit conventions in docs/conventions.md for allowed commit types and breaking-change notation.

When choosing a scope in czg:

Prefer a real workspace scope such as apps/... or common/... when the change is limited to one workspace.
Use docs for documentation-only changes.
Use ci for workflow, hook, or automation changes.
Use repo for root-level or cross-cutting changes that do not fit a single workspace.

Release Automation

Changelog and tag automation are handled by the release-please job in .github/workflows/ci.yml.

The workflow runs release-please-action in manifest mode using
- release-please-config.json and
- .release-please-manifest.json
Releases are tracked per workspace for apps/*.
The workflow requires a GitHub App installation token setup.
Troubleshooting lives in release-troubleshooting.md.

How It Works

A commit lands on main or rel/*.
The release-please job scans merged Conventional Commits for each configured workspace.
If releasable commits exist for one or more workspaces, it opens or updates workspace-scoped release PRs.
When release PRs are merged, release-please updates changelogs, creates workspace-scoped tags, and publishes GitHub releases.

Releasable Commits

feat, fix, and deps trigger a release PR.
chore can appear in the changelog if a release is already happening, but chore by itself does not trigger a release PR.
To force a release version manually, add a Release-As: x.y.z footer to the commit body.

GitHub App Token Setup

Use a GitHub App instead of a PAT if you want release PRs and release-created events to trigger downstream workflows.

Create the GitHub App under GitHub Settings → Developer settings → GitHub Apps → New GitHub App.
Disable webhooks and grant these repository permissions:
- Contents: Read and write
- Pull requests: Read and write
- Issues: Read and write
- Metadata: Read-only
Install the app on this repository.
Add the app ID to variable RELEASE_PLEASE_APP_ID and the PEM private key to secret RELEASE_PLEASE_APP_PRIVATE_KEY.
If your repository or organization restricts workflow-created PRs, enable the setting that allows GitHub Actions to create and approve pull requests.

Once configured, the workflow step uses actions/create-github-app-token to mint a short-lived installation token and passes it to release-please.

If the variable or secret is missing, the workflow fails early instead of falling back to GITHUB_TOKEN.

Rebase Or Merge

Use the repo workflow rather than a per-team merge style.

Day-to-day feature and fix PRs should use squash merge.
Open those PRs from feat/*, fix/*, or chore/* into the active rel/* branch.
Reserve hotfix/* branches for urgent fixes that start from main, merge to main, and are then backported to active rel/* branches.
Use cherry-pick for hotfix backports when the same fix must land in multiple release branches.

This keeps release history predictable for release-please and matches the contributor workflow in .github/CONTRIBUTING.md.

CI

Please read the following scripts for information on the CI workflows

CI Meta workflow ci-meta.yml

Changes must be only to .github/workflows OR .github/actions folder

CI workflow ci.yml

Changes must not be to .github/workflows AND .github/actions folders

Once configured:

PRs show red X if any required check fails.
Merges are blocked until all checks pass and approvals are met.
The branch protection rules apply uniformly across day-to-day work (rel/* branches), production merges (main), and emergency hotfixes.

Note: tests (unit, integration, e2e) are run for touched workspaces only, identified by the detect-touched-workspaces, Skip test if npm script for test not found.

CI Workflow

PR submitted to main or release branches
CI runs on PR submitted

repo-wide format check, no autofix
repo-wide lint check, no autofix
repo-wide schema check, no autofix
repo-wide testing, no autofix
repo-side package audit, no autofix?

Only allow merge if all checks pass

CI Meta Workflow

Make CI changes on a chore/ci/<name> branch.
Use commit messages in Conventional Commit format, for example chore(ci): tighten workflow validation.
Run act locally to validate before pushing.
Push chore/ci/<name> to trigger ci-meta.yml. This workflow only runs for changes under .github/workflows/** and .github/actions/**.
Open a PR from chore/ci/<name> to ci-staging and confirm the workflow is green end-to-end.
After validation, open a PR from ci-staging to main.