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.
• Keep internal ticket ids and Linear URLs out of commit messages, PR titles, and PR descriptions — this repo is public, and a squash merge puts the PR title into main's permanent history. Describe the change on its own terms and carry the identifier in the branch name instead.

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.