gitty

Inspect Git repositories, review pull or merge requests, address review feedback, debug CI failures from workflow files and local history, prepare patches or branches for review, and when requested publish review comments back to GitHub or GitLab through token-authenticated REST calls. Use when Codex receives a repo path, repo URL, PR or MR link, branch name, commit SHA, patch-review request, pasted review feedback, or pasted CI logs and should work from local git state first; when starting from a PR or MR link, clone into the OS temp directory and review locally; when comment publishing or PR creation is requested, validate `GITHUB_TOKEN` or `GITLAB_TOKEN` first and stop if the required token is unavailable or invalid.

Gitty Review

Overview

Operate from local clones and git refs first. Treat connector-provided links, pasted review feedback, and pasted CI logs as entry points, then perform repository discovery, fetching, diffing, history inspection, and patch preparation with git; use GitHub or GitLab REST only for provider-owned actions such as publishing comments or creating a GitHub PR when the user explicitly wants a browser-visible review artifact.

Rules

  • Use git for remote access, repository inspection, diffing, history, blame, patch creation, and review-range setup.
  • Do not use gh, glab, provider MCP tools, or browser scraping.
  • Use provider REST only when git cannot represent the requested action, such as posting GitHub PR comments, GitHub PR reviews, GitLab MR notes, GitLab MR diff discussions, or creating a GitHub PR for review.
  • When provider REST is required, validate the token first with scripts/check-provider-auth.py or the provider /user endpoint.
  • If GITHUB_TOKEN or GITLAB_TOKEN is required and missing or invalid, stop and ask the user to fix it. Do not silently fall back to stored git credentials when the workflow expects explicit REST tokens.
  • If the token exports live in ~/.zshrc or another shell startup file, run the command in a shell that sources that file first, for example zsh -lc 'source ~/.zshrc >/dev/null 2>&1 && ...'.
  • When the user sends only a PR or MR URL, clone into an OS temp directory first with scripts/setup-review-repo.sh.
  • If metadata is not recoverable from git alone, state the gap. Use pasted review comments or logs when available; otherwise ask for the missing text or make one explicit assumption.
  • Keep provenance clear: report the local repo path, base ref, head ref, and any assumption about the target branch.

Connector-First Intake

  • Start from the highest-signal artifact already in the prompt: repo path, repo URL, PR or MR link, pasted comments, or pasted CI logs.
  • Use that artifact only to locate refs, commits, and files. Do the actual repository work with local git commands.
  • Fall back to direct git remote inspection when the connector artifact is incomplete, stale, or missing exact branch metadata.

Quick Start

  1. Existing local repo:
git -C <repo> status --short --branch
git -C <repo> remote -v
git -C <repo> log --oneline --decorate --graph -20
  1. PR or MR link:
scripts/setup-review-repo.sh "<url>"
scripts/review-diff-summary.sh "<repo_path>" "<base_ref>" "<head_ref>"
  1. Feedback or CI logs pasted by the user:

Use the pasted text as evidence, keep the repo checked out locally, and trace the relevant files with git diff, git show, git log, git grep, and git blame.

  1. Provider token check before publishing comments:
zsh -lc 'source ~/.zshrc >/dev/null 2>&1 && scripts/check-provider-auth.py github'
zsh -lc 'source ~/.zshrc >/dev/null 2>&1 && scripts/check-provider-auth.py gitlab'

Workflow

1. Localize the work

  • If the user already gave a repo path, stay in that repo unless they want an isolated temp clone.
  • If the user gave only a repo URL, clone it into temp or a user-chosen path.
  • If the user gave a GitHub PR or GitLab MR link, run scripts/setup-review-repo.sh. The script clones the repo, fetches review refs, checks out the review head, and prints repo_path, base_ref, and head_ref.
  • Read references/provider-ref-patterns.md when the link format or ref mapping is unusual.

2. Build review context with git

  • Resolve the comparison range with git merge-base <base> <head>.
  • Inspect commits first:
git -C <repo> log --oneline --decorate <merge-base>..<head>
  • Inspect file scope:
git -C <repo> diff --name-status <merge-base>..<head>
  • Inspect the actual patch:
git -C <repo> diff --stat <merge-base>..<head>
git -C <repo> diff <merge-base>..<head> -- <path>
  • Inspect history around risky files:
git -C <repo> log --follow -- <path>
git -C <repo> blame -L <start>,<end> <path>
  • Use scripts/review-diff-summary.sh when you want a deterministic first-pass summary.
  • Review with a code-review mindset: correctness, regression risk, migrations, compatibility, feature flags, security, and missing tests.

3. Review a PR or MR from a link

  • Treat the URL as coordinates, not as a source of truth.
  • Review the fetched head locally, not the web UI.
  • Default base_ref to the remote default branch if the target branch is not discoverable from git alone. Call out that assumption in the final response.
  • If the user wants line-specific findings, cite the local file and line numbers from the checked-out tree or diff context.

4. Address review feedback

  • Require the feedback text in the prompt, pasted comments, a local file, or fetch it through provider REST only when the workflow has valid tokens and the user asked for provider-side comment handling.
  • Map each feedback point to the relevant commit, file, or hunk with git log, git show, git diff, and git blame.
  • Make the change on the local branch or detached review checkout, then re-check the minimal diff with:
git -C <repo> diff --stat
git -C <repo> diff -- <path>
  • Summarize what was addressed, what was left unchanged, and any unresolved ambiguity.

5. Publish comments back to GitHub or GitLab

  • Build the review context locally with git before posting anything. Do not comment from web UI impressions alone.
  • Read references/provider-rest-comments.md when provider-side publishing is requested.
  • Validate the token first:
scripts/check-provider-auth.py github
scripts/check-provider-auth.py gitlab
  • GitHub:
POST /repos/{owner}/{repo}/issues/{pull_number}/comments
POST /repos/{owner}/{repo}/pulls/{pull_number}/comments
POST /repos/{owner}/{repo}/pulls/{pull_number}/reviews
  • GitLab:
POST /projects/:id/merge_requests/:merge_request_iid/notes
POST /projects/:id/merge_requests/:merge_request_iid/discussions
  • When the exact diff position is uncertain, prefer a timeline note over an incorrect inline comment.
  • For GitLab diff discussions, get base_sha, start_sha, and head_sha from MR versions and derive the target line from MR changes or a local diff.
  • Return the browser URL of each created comment so the user can inspect it directly.

6. Debug failing Actions or CI checks

  • Without provider APIs, do not claim an exact failing job unless the user supplied the log text or commit SHA.
  • Start from git-visible evidence:
git -C <repo> ls-files ".github/workflows/*" ".gitlab-ci.yml" ".gitlab-ci/*.yml"
git -C <repo> show <sha>:<workflow-path>
git -C <repo> log -- <workflow-path>
git -C <repo> grep -n "<script-or-command>" HEAD
  • Compare the failing revision to the last known good commit with git diff and git log.
  • If local reproduction is needed, use the repo's own commands only after the git inspection isolates the likely failing area. The hard restriction is on provider interaction: use git instead of GitHub or GitLab APIs or CLIs.

7. Prepare changes for review

  • Keep the branch state explicit:
git -C <repo> status --short --branch
git -C <repo> diff --cached
git -C <repo> diff <base>...HEAD
git -C <repo> log --stat <base>..HEAD
  • Prefer shareable git artifacts:
git -C <repo> format-patch <base>..HEAD
git -C <repo> bundle create <name>.bundle <base>..HEAD
  • Do not push or force-push unless the user explicitly asks.
  • If the user explicitly wants a browser-visible GitHub review artifact and the branch is already pushed, creating a PR through GitHub REST is acceptable after token validation.
  • If the user explicitly wants a GitLab MR created, treat it as provider REST work and stop if the required token, project ID, or target branch metadata is missing.

Resources

  • scripts/setup-review-repo.sh Clone a repo or PR or MR review target into a temp directory, fetch provider-specific refs, and print the local review coordinates.
  • scripts/review-diff-summary.sh Resolve the merge base for a base or head pair and print a compact git-native review summary.
  • scripts/check-provider-auth.py Validate GITHUB_TOKEN or GITLAB_TOKEN and print the authenticated account in a machine-friendly format.
  • references/git-review-playbook.md Command patterns for repo inspection, review, feedback handling, CI triage, and patch prep.
  • references/provider-ref-patterns.md URL-to-ref rules for GitHub PRs and GitLab MRs, plus the assumptions to surface when git alone cannot recover metadata.
  • references/provider-rest-comments.md Token requirements, auth validation, and endpoint patterns for GitHub PR comments and GitLab MR notes or discussions.