Local vs CI

Contractual is git-agnostic by design. The CLI never commits, tags, or pushes. You control your git history. The GitHub Action handles release automation.

The philosophy

Other tools in this space take different approaches:

Tool	Git Operations	Philosophy
Lerna	CLI does commits, tags, push	CLI owns the workflow
Changesets	CLI creates intent files only	GitHub Action executes
Contractual	CLI is git-agnostic	Clear separation of concerns

Contractual takes the Changesets approach: the CLI is purely for local work. All git and GitHub operations happen through the Action.

What the CLI does

The CLI handles spec governance and change description:

Command	Purpose
`contractual lint`	Validate specs against linters
`contractual diff`	Show changes vs. last snapshot
`contractual breaking`	Check for breaking changes (CI gate)
`contractual changeset`	Create a changeset file
`contractual version`	Bump versions and update files
`contractual status`	Show current versions and pending changes

All of these commands read and write local files only. None of them:

Run git commit
Run git tag
Run git push
Create GitHub Releases
Post PR comments

What the CLI does NOT do

The CLI explicitly avoids git operations:

Operation	Who does it
Commit changes	You (`git commit`)
Push to remote	You (`git push`)
Create PRs	You (GitHub UI or `gh pr create`)
Create git tags	GitHub Action
Create GitHub Releases	GitHub Action
Post PR comments	GitHub Action

What the GitHub Action does

The Action handles automation and GitHub integration:

Mode	Trigger	What it does
`pr-check`	PR opened/updated	Lint, diff, post comment
`release`	Push to main	Create Version PR if changesets exist
`release`	Version PR merged	Create tags and GitHub Releases

Why this design?

1. Predictability

No surprise git operations. When you run contractual version, it updates files but doesn’t commit them. You decide when to commit.

2. Flexibility

Works with any git workflow:

Trunk-based development
Gitflow
GitHub Flow
Any branching strategy

The CLI doesn’t care about your branches or merge strategy.

3. Reviewability

All version changes go through PRs:

Feature PRs contain spec changes + changesets
Version PRs contain version bumps + changelog updates

Both are reviewable before merge.

4. Control

You own your git history:

Squash commits? Up to you.
Rebase before merge? Your choice.
Amend commit messages? Go ahead.

Contractual doesn’t fight your git preferences.

FAQ

Why doesn’t the CLI commit?

Because git workflows vary. Some teams squash, some merge, some rebase. Some require signed commits. Some have pre-commit hooks. The CLI can’t know your git requirements, so it stays out of the way.

Can I use Contractual without the GitHub Action?

Yes. The CLI works standalone:

# Local workflow without Action
contractual lint
contractual diff
contractual changeset
# ... manually commit and push ...
contractual version
# ... manually commit, tag, and push ...

You lose the automation (PR comments, Version PRs, auto-tags), but the core governance works.

What if I want the CLI to commit?

That’s not Contractual’s philosophy. If you want a tool that commits, consider Lerna or semantic-release. Contractual is for teams who want to control their git history.

Does the Action require special permissions?

The Action needs:

contents: write - to create Version PRs and tags
pull-requests: write - to post comments

For creating Version PRs, it needs a Personal Access Token (PAT) to trigger downstream workflows.