Sentinel Docs

Sentinel uses a conventional-commit release pipeline with local hooks, CI gates, and release automation. The process is designed to keep versioning predictable and release output clean.

Commit And PR Discipline

Use Conventional Commits for branch commits and pull request titles.
The commit-msg hook enforces commit format locally through commitlint.
CI validates pull request titles so release PRs and changelog entries remain consistent after squash merges.

Example:

feat(chat): add Codex CLI fallback

Local Checks

Hooks are installed automatically on bun install through lefthook.

pre-commit formats staged source, config, and docs files with prettier.
commit-msg validates the commit message.
pre-push runs bun run typecheck and bun run test.

If you need to run the same checks manually:

bun run format:check
bun run typecheck
bun run test

CI Gates

The main CI workflow is split into stable branch-protection jobs:

changes
pr-metadata
format
typecheck
test

changes uses path-aware filters so docs-only pull requests skip typecheck and test.

The default CI gate keeps automated test coverage on ubuntu-24.04 for the fastest and lowest-cost signal. Windows and Linux desktop parity checks still belong in desktop-verify plus the manual platform smoke checklist before release.

Desktop Verification

Use the desktop-verify workflow to test desktop packaging before a tag exists.

Open GitHub Actions and run desktop-verify.
Set git_ref to the branch, commit SHA, or tag you want to validate.
Leave platforms as linux for the cheapest default verification.
Select mac, windows, or all only when you need platform-specific validation.
Review the uploaded workflow artifacts.
Complete the manual Windows/Linux smoke flow in Desktop platform smoke checklist for any platform you intend to ship.

This workflow never creates or updates a GitHub Release. It is also not complete until the matching platform smoke checklist has been executed by an owner.

Releases

main is the only release branch.

release-please prefers a repository secret named RELEASE_PLEASE_TOKEN.

A dedicated PAT or fine-grained token remains the simplest option because its tag push triggers publish-release directly.
If RELEASE_PLEASE_TOKEN is missing, the workflow falls back to the default GITHUB_TOKEN and then explicitly dispatches publish-release for the created tag.
This fallback keeps releases working without a separate token, but the downstream build comes from workflow_dispatch instead of the tag push event.

Merge pull requests with conventional titles into main.
The release-please workflow opens or updates the release PR.
Merging the release PR updates package.json, .release-please-manifest.json, and CHANGELOG.md, then creates the matching vX.Y.Z tag.
The publish-release workflow starts automatically from that tag, builds macOS, Windows, and Linux desktop artifacts, and updates the GitHub Release using the matching CHANGELOG.md section as the release body.
macOS releases publish separate arm64 and x64 DMG assets so Apple Silicon and Intel users can download the correct build directly.

CHANGELOG.md is automation-managed by release-please, but it is also the release-summary source of truth. Review the changelog entry in the release PR carefully before merging.

The repository currently stays on a patch-only 0.0.x release line. Exiting that temporary policy later should require only a release-please config change, not a workflow redesign.

Manual Rebuilds

publish-release remains manually dispatchable for rebuilding or republishing an existing release tag only.

It always builds the exact tagged commit.
It no longer accepts an override ref.
Use desktop-verify for untagged branches, SHAs, or packaging fixes that still need validation before release.

Release Process