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

- Skill: `right-git/gitty` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add right-git/gitty`
- Raw SKILL.md: https://api.skillmd.com/api/skills/right-git/gitty/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: right-git (https://skillmd.com/u/right-git)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/right-git/gitty

---


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

```bash
git -C <repo> status --short --branch
git -C <repo> remote -v
git -C <repo> log --oneline --decorate --graph -20
```

2. PR or MR link:

```bash
scripts/setup-review-repo.sh "<url>"
scripts/review-diff-summary.sh "<repo_path>" "<base_ref>" "<head_ref>"
```

3. 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`.

4. Provider token check before publishing comments:

```bash
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:

```bash
git -C <repo> log --oneline --decorate <merge-base>..<head>
```

- Inspect file scope:

```bash
git -C <repo> diff --name-status <merge-base>..<head>
```

- Inspect the actual patch:

```bash
git -C <repo> diff --stat <merge-base>..<head>
git -C <repo> diff <merge-base>..<head> -- <path>
```

- Inspect history around risky files:

```bash
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:

```bash
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:

```bash
scripts/check-provider-auth.py github
scripts/check-provider-auth.py gitlab
```

- GitHub:

```text
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:

```text
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:

```bash
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:

```bash
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:

```bash
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.