Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
176 changes: 176 additions & 0 deletions .github/workflows/claude-code-review.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,176 @@
# Automatic Claude review of pull requests, built around how these docs work:
# the docs describe what the CLI and the GitHub Action actually do, every link
# resolves, nothing internal lands in a public repo, and the pages sound like
# patch-it. It ends with a clear verdict.
#
# Runs once per PR: when it's opened (not as a draft), marked ready, or reopened.
# New pushes don't re-run it, to save Claude usage. For a fresh review after
# changes, a maintainer comments `@claude review` (claude.yml).
#
# Pull requests from forks: GitHub gives their runs no secrets, so this
# workflow only runs for branches in this repository. On a fork's PR a
# maintainer comments `@claude review` instead; claude.yml reviews it read-only
# and never runs the fork's code. This workflow never uses `pull_request_target`.
#
# Auth: CLAUDE_CODE_OAUTH_TOKEN, a Claude subscription token from
# `claude setup-token`. Until it's available the job skips with a notice.
#
# Note: a PR that edits this file can't run it. The action refuses to run a
# workflow that differs from the one on main, so changes here only take effect
# after they merge.
name: Claude Code Review

on:
pull_request:
types: [opened, ready_for_review, reopened]

# One review per PR at a time; a newer trigger cancels the run it supersedes.
concurrency:
group: claude-review-${{ github.event.pull_request.number }}
cancel-in-progress: true

jobs:
review:
# Drafts are work in progress; review them once they're marked ready.
# Only branches in this repository: a fork's run gets no secrets.
if: >-
github.event.pull_request.draft == false &&
github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
pull-requests: write # the review comment and inline comments
issues: write # PR comments go through the issues API
id-token: write # the action authenticates as the Claude GitHub App
env:
# Skip quietly instead of failing red until the secret is available.
HAS_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
steps:
- name: Skip (CLAUDE_CODE_OAUTH_TOKEN not set)
if: env.HAS_TOKEN != 'true'
run: echo "::notice::CLAUDE_CODE_OAUTH_TOKEN is not set; skipping Claude review."

- uses: actions/checkout@v6
if: env.HAS_TOKEN == 'true'
with:
fetch-depth: 1

# Node, so Claude can verify the site builds instead of only reading.
- uses: actions/setup-node@v6
if: env.HAS_TOKEN == 'true'
with:
node-version: 22
cache: npm

- uses: anthropics/claude-code-action@v1
id: claude
if: env.HAS_TOKEN == 'true'
env:
# Any sub-agent Claude starts at the Opus tier also runs Opus 5.5.
ANTHROPIC_DEFAULT_OPUS_MODEL: claude-opus-5-5
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
# The action creates the review comment itself and Claude fills it in,
# so a review can never end in silence. Sticky: one comment per PR.
track_progress: true
use_sticky_comment: true
# Public repo: the run summary is public, so don't print Claude's report there.
display_report: false
prompt: |
REPO: ${{ github.repository }}
PR NUMBER: ${{ github.event.pull_request.number }}

Review this pull request to patch-it's public docs (docs.patch-it.dev, Astro
Starlight). Read README.md first: it says where pages live, how the plugin list
and llms.txt are generated, and what stays out of this repo.

HOW TO RUN COMMANDS: one plain command per Bash call. Pipes (|), redirects
(>), `&&`, `;` and `$(...)` are blocked and will waste a turn. Read files
with the Read tool, and search with Grep/Glob, never with cat, grep or find.

1. THE CHANGE. Read the PR title and body with `gh pr view <PR NUMBER>`, and
any issue it references with `gh issue view <number>`. Read the diff with
`gh pr diff <PR NUMBER>`, and changed pages in full.
2. MATCHES THE PRODUCT. The patch-it CLI and GitHub Action are the reference:
their README and docs say what a command, flag, Action input, config key,
exit code or API field does. You can't read that repo from here, so:
- check the change agrees with the rest of these docs (configuration/,
guides/cli.md, guides/github-action.md, api-reference/), and flag every
contradiction;
- for each behavior the PR describes (a new input, flag, default, exit code,
endpoint or field), the PR body should link the client change or release
it documents. If it doesn't, list those claims under "Needs a maintainer
to confirm" instead of guessing;
- don't document what isn't shipped: "coming soon" stays a
`:::note[Coming soon]` aside, not a described feature.
3. LINKS RESOLVE. Every link in a changed page: site links like
`/guides/cli/` must match a page under src/content/docs/ (guides/cli.md or
.mdx), and a `#anchor` must match a heading on that page. Relative links and
images must point at real files. List external links you couldn't check.
4. NOTHING INTERNAL. This repo is public. Flag credentials, tokens, keys,
internal hostnames, internal APIs or services, architecture or runbook
details, links to private repos, dashboards or tickets, customer or user
names, unsourced numbers, prices, roadmap dates, and links to AI sessions.
Internal details belong in the private handbook, not here.
5. GENERATED PARTS. The table in supported-apis/plugins.md comes from
patch-it-plugins' docs/plugins.md: a hand edit between the plugins markers is
blocking. A new page needs the frontmatter (title, description, sidebar
order where the folder needs it); llms.txt picks pages up by itself.
6. VOICE. Calm, sharp, wry; in docs, clear first, at most a dry aside in an
intro, never in steps. Always lowercase "patch-it". Name the real thing
(API version, model ID, date, file) and link to the source. No emoji, no
exclamation marks, no hype: never "revolutionary", "seamless",
"AI-powered", "leverage", "effortless", "magic", "supercharge", "unlock",
"empower", "best-in-class", "cutting-edge". Say "fix" (not remediate),
"breaking change" (not issue or incident), "pull request" or "PR".
Wording notes are non-blocking.
7. VERIFY BY RUNNING. Run `npm ci`, then `npm run build`; it must finish
without errors. Report what you ran and what happened; don't claim anything
you didn't check.

Your final comment is what the author reads, and it is public. Start with ONE
verdict line: "✅ Ready to merge", "⚠️ Merge after fixes" or "❌ Not ready",
with a one-sentence reason. Then, concisely:
- **Accuracy**: contradictions found, and "Needs a maintainer to confirm"
- **Links**: broken links, or "all resolve"
- **Public**: anything internal, or "nothing found"
- **Verified**: the commands you ran and their results
- **Non-blocking**: voice and wording suggestions, clearly marked as such
Put each specific problem as an inline comment on its line.
Never include a Claude session ID or claude.ai link.
# Read-only on GitHub, plus the npm install and build to verify.
# No `gh pr comment` and no `gh api`: the action posts the review comment
# itself. Default permission mode: anything not listed here is denied.
claude_args: >-
--model claude-opus-5-5
--permission-mode default
--allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*),Bash(npm ci),Bash(npm run build)"
--disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*)"

# Diagnostics only: print the number of blocked tool calls and which tools,
# so a disappointing review can be fixed instead of guessed at. Public repo:
# it doesn't print Claude's message or the tool inputs.
- name: Log blocked tool calls
if: always() && env.HAS_TOKEN == 'true' && steps.claude.outputs.execution_file != ''
continue-on-error: true
env:
EXECUTION_FILE: ${{ steps.claude.outputs.execution_file }}
run: |
python3 - <<'PY'
import json, os

try:
data = json.load(open(os.environ["EXECUTION_FILE"]))
except Exception as e:
print(f"No execution output to read: {e}")
raise SystemExit(0)

messages = data if isinstance(data, list) else [data]
result = next((m for m in reversed(messages) if m.get("type") == "result"), {})
denials = result.get("permission_denials") or []

print(f"=== Blocked tool calls: {len(denials)} ===")
for d in denials:
print(f"BLOCKED {d.get('tool_name')}")
PY
71 changes: 71 additions & 0 deletions .github/workflows/claude.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Claude on demand: a maintainer mentions @claude in a PR comment, a review or a
# review comment, and Claude replies in the same thread. `@claude review` on a
# PR gets a full review of the docs change, including PRs from forks.
#
# This repo is public, so this workflow is locked down:
# - Only maintainers trigger it: the commenter's author_association must be
# OWNER, MEMBER or COLLABORATOR, or no runner starts. The action then checks
# write access itself. Bots can't trigger it.
# - Read and comment only. Claude can read the repo and the PR, and reply; it
# can't edit files, commit, push, run commands or fetch web pages
# (`--permission-mode default`, so anything not allowed below is denied).
# - On a fork's PR the action checks out the fork's code to read, but restores
# Claude's config (CLAUDE.md, AGENTS.md, .claude/) from main, and Claude runs
# none of the fork's code. Never uses `pull_request_target`.
#
# Auth: CLAUDE_CODE_OAUTH_TOKEN, same as claude-code-review.yml.
name: Claude

on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
pull_request_review:
types: [submitted]

jobs:
claude:
# Only a maintainer's comment that mentions @claude starts a runner.
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude') &&
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude') &&
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association)) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude') &&
contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.review.author_association))
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
pull-requests: write # replies and inline comments
issues: write # PR comments go through the issues API
id-token: write # the action authenticates as the Claude GitHub App
actions: read # lets Claude read CI results on PRs
env:
HAS_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
steps:
- name: Skip (CLAUDE_CODE_OAUTH_TOKEN not set)
if: env.HAS_TOKEN != 'true'
run: echo "::notice::CLAUDE_CODE_OAUTH_TOKEN is not set; skipping Claude."

# The base branch. The action itself checks out the PR's code to read.
- uses: actions/checkout@v6
if: env.HAS_TOKEN == 'true'
with:
fetch-depth: 1

- uses: anthropics/claude-code-action@v1
if: env.HAS_TOKEN == 'true'
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
# Public repo: the run summary is public, so don't print Claude's report there.
display_report: false
# Read-only plus commenting. No Bash beyond reading the PR and issues,
# no edits, no commits or pushes, no web.
claude_args: >-
--model claude-opus-5-5
--permission-mode default
--allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*)"
--disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*),Bash(git add:*),Bash(git rm:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files"
--append-system-prompt "This is patch-it-docs, the public docs at docs.patch-it.dev (Astro Starlight; pages in src/content/docs/). Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check: (1) accuracy: the patch-it CLI and GitHub Action are the reference, which you can't read from here, so flag contradictions with the rest of these docs (configuration/, guides/cli.md, guides/github-action.md, api-reference/) and list behavior claims the PR body doesn't back with a link to the client change under 'Needs a maintainer to confirm'; unshipped features stay a Coming soon note; (2) links resolve: site links like /guides/cli/ match a page under src/content/docs/, anchors match a heading, relative links and images point at real files; (3) nothing internal: no credentials, internal hostnames, internal APIs or services, architecture or runbook details, links to private repos or tickets, customer names, unsourced numbers, prices, roadmap dates, or links to AI sessions; (4) the plugin table in supported-apis/plugins.md is generated from patch-it-plugins, so a hand edit between its markers is blocking; (5) voice, non-blocking: calm, sharp, wry, clear first; always lowercase patch-it; no emoji, exclamation marks or hype words (revolutionary, seamless, AI-powered, leverage, effortless, magic, supercharge, unlock, empower); say fix, breaking change, pull request. You can't run the build. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then accuracy, links, public, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link."
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,10 @@ npm run build # static site in dist/
npm start # serves dist/ on $PORT (what Railway runs)
```

## Reviews

Claude reviews each pull request once, when it's opened or marked ready (`.github/workflows/claude-code-review.yml`): the docs match what the CLI and the Action do, links resolve, nothing internal, the voice. PRs from forks get no secrets, so for those a maintainer comments `@claude review` and Claude reviews it read-only (it never runs a fork's code). Only maintainers can call `@claude` (`claude.yml`). Claude's review helps; a maintainer still decides.

## Deploy (Railway)

- **Build command:** `npm run build`
Expand Down
Loading