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.

Branch names

• Copy Linear's git branch name (lfe-XXXX-short-title), or the issue's gitBranchName when Linear MCP is available.
• Cursor agents must not use a cursor/ prefix, even if a Cursor Cloud prompt asks for one. Repo guidance wins.
• Keep a username prefix only when Linear's copied name already includes one.

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.
• When a change is too large for one reviewable PR, split it into a chained stack of small PRs instead of widening one.
• Open PRs as reviewable, not as drafts, unless a human asks for a draft.
• Cursor agents apply the GitHub cursor label after opening a PR; see cursor-agents-workflow. Do not leave that tag for a human.
• Do not post GitHub PR comments as the human author. Cursor agents that comment as Cursor should leave one last comment with proof of user-visible work (screenshot, video, or before/after on the PR, not only in chat) and what to doubt in review; see cursor-agents-workflow. Claude Code and other tools that comment as the user must skip that comment.
• Claude, Greptile, or Codex review comments (claude[bot], Claude Code, security-review action, greptile-apps[bot], chatgpt-codex-connector[bot]): do not reply. Keep the thread open until you apply the fix and resolve it, or skip it because you are sure, tell the human in plain language (and invite them to doubt that skip), then resolve it. Do not post @claude review again unless a human asks for another pass. Human reviewer comments stay open and may need a real reply.

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.
• The ECS deployment workflow includes ai-gateway only for staging: pushes to main and manual staging deployments. Its image builds from ai-gateway/ with BUILD_ID set to the commit SHA; production deployments exclude it.
• Do not change release/versioning flow without updating this skill and the impacted package guides.