git-workflow

---
name: git-workflow
description: |
  Langfuse repo Git, GitHub, commit, branch, pull request, issue search,
  release, and production-promotion workflow. Use when staging, committing,
  pushing, opening PRs, choosing a Linear git branch name, handling Claude,
  Greptile, or Codex review comments, searching GitHub issues, or changing
  release/promotion behavior.
---

# 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.