Git Workflow

Git Workflow

Use this skill for repo-specific Git, GitHub, pull request, and release

operations.

Safety

• Inspect git status before staging or committing.
• Do not stage unrelated working-tree changes.
• Do not revert unrelated working-tree changes.
• Do not use destructive commands such as git reset --hard or

git checkout -- unless explicitly requested.

• Keep commits focused and atomic.
• Never add secrets or credentials to the repo.

Commits and Pull Requests

• Commit messages and PR titles must follow Conventional Commits:

type(scope): description or type: description.

• Use feat for new features and fix for bug fixes.
• Use a scope when it clarifies the affected area, for example

fix(api): handle missing trace id.

• Mark breaking changes with ! in the type/scope or a BREAKING CHANGE:

footer.

• PR titles are validated by .github/workflows/validate-pr-title.yml.
• In PR descriptions, list impacted packages and executed verification

commands.

GitHub

• Use gh search issues for GitHub issue search.
• Prefer non-interactive Git and GitHub commands where possible.
• Keep PRs narrow enough to review without unrelated refactors.

Release

• Releases are cut with pnpm run release, run on the branch being released.

Allowed release branches are main and v3

(scripts/release-preflight.sh owns the allowlist).

• main is the current line and the only branch that ships to Langfuse

Cloud. v3 is the OSS maintenance line: a release from it produces a tag,

GitHub release, and Docker images, but never a Cloud deploy.

• On any vX.Y.Z tag push, .github/workflows/release.yml promotes main

to production only if the tagged commit is an ancestor of main;

maintenance-branch tags skip promotion. The production migration

confirmation in the release preflight likewise only runs for main.

• Promote main to production without a release via

.github/workflows/promote-main-to-production.yml or

pnpm run release:cloud (both main-only).

• The latest-release markers track the current major line: pipeline.yml

gates the Docker latest tag on refs/tags/v4, and maintenance branches

disable that gate and set release-it.github.makeLatest: false in their

root package.json so their releases never claim the Docker latest tag

or the GitHub "Latest release" badge. At the next major GA (v5), repeat

the flip: move the gate to refs/tags/v5 on main, then disable it and

set makeLatest: false on the new v4 maintenance branch.

• Do not change release/versioning flow without updating this skill and the

impacted package guides.