Skip to content

ci: migrate Claude auto-review workflow from old docs repo#127

Draft
samgutentag wants to merge 3 commits into
mainfrom
sam-gutentag/migrate-claude-review-workflow
Draft

ci: migrate Claude auto-review workflow from old docs repo#127
samgutentag wants to merge 3 commits into
mainfrom
sam-gutentag/migrate-claude-review-workflow

Conversation

@samgutentag
Copy link
Copy Markdown
Member

@samgutentag samgutentag commented May 28, 2026 •
edited
Loading

What

Migrates the Claude review workflow from the old trunk-io/docs repo to docs2, as an advisory-only docs reviewer.

On every PR, anthropics/claude-code-action reviews the diff for typos, grammar, formatting, and docs best practices and leaves inline comments. It does not approve or merge, and it is not a required status check, so it never blocks a merge. PRs on trunk-merge/ branches are skipped.

Blocker before this works

docs2 has no ANTHROPIC_API_KEY secret (the old docs repo had it). The review step will keep skipping until an org admin adds it:

gh secret set ANTHROPIC_API_KEY --repo trunk-io/docs2

Secrets are write-only, so the admin needs the key value on hand from wherever Trunk stores it.

Why the check is green but the review hasn't run

GitHub won't let a code-review action run with write permissions from a PR branch until the identical workflow file is on the default branch. On this PR (which introduces the file) the action self-skips by design and only starts working once merged to main. The first real review lands on the next PR after this merges (and after the secret is set). A green check here means "the reviewer correctly stayed out of the way," not "the reviewer ran."

Notes

  • Kept actions/checkout@v6 from the source; the other two docs2 workflows pin @v4. Cosmetic.
  • Filename is .yaml to match the source; the other docs2 workflows use .yml. Cosmetic.
  • A copy of this workflow also lives as a reusable template in samgutentag/gutils (templates/github-workflows/), including notes on switching it to auto-approve later if wanted.

🤖 Generated with Claude Code

samgutentag and others added 2 commits May 28, 2026 13:25
@samgutentag @claude
ci: migrate Claude auto-review workflow from old docs repo
634c948 
Ports .github/workflows/claude-review.yaml from trunk-io/docs. Runs
claude-code-action on PRs to review docs for typos, grammar, formatting,
and docs best practices, then auto-approves when the structured review
passes. Skips trunk-merge/ branches.

Requires the ANTHROPIC_API_KEY repo secret (not yet set on docs2).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@samgutentag @claude
ci: guard approve gate against empty review output
4c31948 
The approve step ran fromJSON(structured_output), which throws
"template is not valid" when the review step emits no output. That
happens on the PR that introduces the workflow (claude-code-action
self-skips until the file is on the default branch), and would also
happen if the API key were missing or the action errored.

Default the empty case to '{}' so the gate skips cleanly instead of
failing the job.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@mintlify
Copy link
Copy Markdown
Contributor

mintlify Bot commented May 28, 2026 •
edited
Loading

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
trunk 🟢 Ready View Preview May 28, 2026, 8:31 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@samgutentag @claude
ci: make Claude review advisory-only
213bd22 
Drop the auto-approve step so the workflow only leaves inline review
comments. Removes gh pr review from allowed tools (Claude can no longer
approve), drops the now-unused JSON schema and review_passed prompt, and
renames the check to "Claude Docs Review" to shed the "Auto" connotation.

Not a required status check; runs on every PR but never blocks merge.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@samgutentag samgutentag marked this pull request as draft May 29, 2026 18:11
@samgutentag
Copy link
Copy Markdown
Member Author

samgutentag commented May 29, 2026

Verification status (2026-05-29): unknown

Could not determine rollout state from available signals. Chaining to verify-docs-against-code for content-accuracy check.

  • Flag state: LaunchDarkly not consulted (not applicable, no product feature).
  • Eng PR: none. This PR migrates a CI workflow file (.github/workflows/claude-review.yaml) into docs2; there is no trunk2 eng PR and no Linear ticket in the body.
  • Flag: none.
  • Signals: this is repo infrastructure (an advisory-only Claude review GitHub Action), not a customer-facing product feature, so the rollout-verification model does not apply. The PR's own body notes it is blocked on an ANTHROPIC_API_KEY org secret and self-skips until merged to the default branch. No product behavior to verify against prod.

Next: this is a CI/infra PR, not a feature doc. Merge on the usual code-review basis once the ANTHROPIC_API_KEY secret is in place; the rollout verdict is not meaningful here. Flipped to draft per the non-live default.

@samgutentag
Copy link
Copy Markdown
Member Author

samgutentag commented May 29, 2026

Code verification (2026-05-29): no claim candidates found

This PR adds a single CI workflow file (.github/workflows/claude-review.yaml) and changes no documentation content. There are no factual product claims (API field names, numeric limits, paths, CLI flags) to verify against Trunk source.

The file's only Trunk-specific reference is the trunk-merge/ head-ref skip condition (if: ${{ !startsWith(github.head_ref, 'trunk-merge/') }}), which matches the merge-queue branch prefix in source (trunk-io/trunk/.../controller/utils/index.ts). Everything else is workflow config and third-party action pins (anthropics/claude-code-action@v1, actions/checkout@v6), which are out of scope for code verification.

No draft change or label from this skill. (Chained automatically because verify-docs-pr returned unknown for this infra PR.)

@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented May 31, 2026

Verification status (May 31, 2026): unknown

No eng PR references, no Linear ticket, and no LaunchDarkly flag detected — cannot determine shipping readiness automatically.

  • Flag state: not consulted
  • Eng PR: none found
  • Flag: none
  • Signals: PR touches CI workflow migration docs; no external signals to anchor verdict

Next action: author or reviewer to confirm whether the CI workflow changes are live in prod, then update verdict.

Generated by Claude Code

@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented Jun 1, 2026

Docs Verify Sweep · June 1, 2026 · ❓ unknown

Could not determine feature status — no linked eng PR or feature flag found, or signals were unclear. Manual review required.

Unchanged from previous sweep (May 31, 2026).

Generated by Claude Code

@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented Jun 2, 2026

Verification status: unknown - June 2, 2026

Could not determine rollout state from available signals.

  • Flag state: Not applicable; this is a CI workflow migration, not feature documentation
  • Eng PR links: None
  • Flag: none
  • Signals checked: PR body; no feature to verify
  • Suggested next action: CI infrastructure PR. Human review of workflow configuration needed. The ANTHROPIC_API_KEY secret must be set before the workflow can run (see PR body for instructions).

Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@samgutentag