Document ACP backend for PR reviews

[xingyaoww]

Summary

• Add an experimental ACP review backend section to the automated code review use case.
• Document the Codex ACP workflow, including how to create CODEX_AUTH_JSON_B64 from a local device-code login and restore it on a trusted self-hosted runner.
• Update the PR review action input table with ACP-related inputs and regenerate llms.txt / llms-full.txt.

Validation

• make llms-check

[mintlify]

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

Project	Status	Preview	Updated (UTC)
all-hands-ai	🟢 Ready	View Preview	Apr 28, 2026, 5:59 PM

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

[all-hands-bot]

Review Summary

🟡 Acceptable - Comprehensive documentation with one improvement opportunity

This PR adds well-structured documentation for the ACP (Agent Client Protocol) backend for PR reviews, including detailed setup instructions, security warnings, and examples.

---

Strengths

✅ Security Handling - Excellent security warnings and credential management guidance:

• Clear warnings about experimental status and trusted runner requirements
• Proper credential handling with restrictive permissions (chmod 600)
• Cleanup steps included in workflow examples
• Uses printf '%s' instead of echo to avoid newline issues

✅ Documentation Quality:

• Step-by-step Codex ACP setup instructions
• Clear examples with complete workflows
• Appropriate use of warning/note callouts
• Good deprecation notice for review-style parameter

✅ Custom Skill Naming - Excellent warning about not naming custom skills code-review to avoid conflicts with plugin skills

---

[IMPROVEMENT OPPORTUNITIES]

Breaking Change - Action Path Migration

The action path has changed from:

# OLD
uses: OpenHands/software-agent-sdk/.github/actions/pr-review@main

# NEW  
uses: OpenHands/extensions/plugins/pr-review@main

This is a breaking change for existing users. Consider adding a prominent migration notice at the top of the PR review documentation:

<Note>
**Action Path Updated:** The PR review action has moved to the extensions repository. Update your workflows:
- **Old:** `OpenHands/software-agent-sdk/.github/actions/pr-review@main`
- **New:** `OpenHands/extensions/plugins/pr-review@main`
</Note>

This will help users avoid workflow failures when they update their documentation references.

---

[RISK ASSESSMENT]

⚠️ Risk Assessment: 🟢 LOW

This is primarily a documentation PR with the following characteristics:

• Adds documentation for experimental ACP backend feature (clearly marked)
• Includes appropriate security warnings for credential handling
• Deprecates review-style parameter in backward-compatible way (still has default value)
• Large diff size (119k chars) but well-organized
• One breaking change (action path) that could use better migration guidance

No blocking issues. The breaking change is in documentation references (not code), so existing workflows will continue to work until users manually update their documentation references.

---

VERDICT:
✅ Worth merging - Solid documentation with appropriate warnings. The migration notice is a nice-to-have improvement but not blocking.

KEY INSIGHT:
The Codex ACP authentication workflow is well-designed with proper security considerations (restrictive permissions, cleanup, clear warnings about trusted runners). The experimental feature is appropriately flagged, making it clear this is for advanced use cases only.

[xingyaoww]

@OpenHands Please merge from main and resolve the merge conflict, and make sure you've reflected all the changes we've been incorporating in this PR. OpenHands/extensions#210

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary of Work

Request Checklist

• ✅ Merge from main — Successfully merged origin/main into docs/pr-review-acp-backend, resolving the merge conflict in llms-full.txt (the only conflicted file).
• ✅ Resolve merge conflict — Resolved by accepting the main branch version of the generated file, then regenerating it.
• ✅ Reflect changes from extensions PR docs: sync code blocks and generate API reference #210 — Reviewed the now-merged extensions PR #210 and aligned the docs with the actual action.yml:
  • Fixed input name mismatch: review-agent-mode → agent-kind across all references (input table, prose, and YAML example).
  • Added missing inputs to the table: require-evidence, use-sub-agents, lmnr-api-key, enable-uv-cache.
  • Updated llm-model description and default to match the action (anthropic/claude-sonnet-4-5-20250929, with A/B testing note).
• ✅ Regenerated llms.txt / llms-full.txt — make llms-check passes cleanly.
• ✅ Pushed to the PR branch — Changes are live on the PR.

Conciseness

All changes are directly relevant to the request. The only files modified were:

• openhands/usage/use-cases/code-review.mdx (the actual content fix)
• llms.txt and llms-full.txt (required regeneration of generated files)

No extraneous changes were introduced.

[xingyaoww]

@OpenHands iterate until all-hands-bot approves this PR

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[all-hands-bot]

🟡 Acceptable - Comprehensive ACP backend documentation with one minor verification needed

---

This PR adds thorough documentation for the experimental ACP review backend, including clear security warnings, detailed setup instructions, and a complete Codex workflow example. The documentation follows best practices for credential handling and runner isolation.

One model name in the example should be verified to ensure it references a real/available model.

[all-hands-bot]

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

This is a documentation-only change with no code modifications. The documentation introduces an experimental feature with appropriate security warnings, follows credential handling best practices (base64 encoding, cleanup with if: always(), file permissions 600), and restricts usage to trusted self-hosted runners. The comprehensive input table and clear examples reduce the risk of misconfiguration.

---

VERDICT:
✅ Worth merging: Documentation is thorough and follows security best practices. One model name should be verified, but this doesn't block merging.

KEY INSIGHT:
The documentation successfully balances the need to document an experimental feature while maintaining strong security guidance through clear warnings and example best practices.

[xingyaoww]

Addressed feedback in 71edf95 — added action path migration notice in the Composite Action section as suggested. Ready for another look.

[all-hands-bot]

🟡 Acceptable - Comprehensive ACP backend documentation with one unresolved verification needed

---

This PR adds thorough documentation for the experimental ACP review backend feature, including:

✅ Clear structure - Well-organized sections with progressive disclosure
✅ Security guidance - Prominent warnings about trusted runners and credential handling
✅ Complete examples - Full workflow with Codex ACP including credential setup and cleanup
✅ Updated references - Action path migration note and comprehensive input parameter table
✅ Auto-generated files - llms.txt files properly regenerated

[IMPROVEMENT OPPORTUNITIES]

The unresolved thread from previous reviews regarding the gpt-5.5 model identifier should be addressed - please verify this is the correct model name for Codex ACP or update to a known-available model.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

Documentation-only changes with no runtime code modifications. Adds optional experimental feature documentation with appropriate security warnings. Auto-generated doc files were properly validated with make llms-check.

VERDICT:
✅ Worth merging - High-quality documentation with one minor verification needed

KEY INSIGHT:
The ACP integration documentation follows security-first principles by requiring explicit trusted runner setup and credential cleanup, preventing accidental exposure of subscription credentials in untrusted workflows.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Install the iterate skill in your agent and run /iterate to automatically drive this PR through CI, review, and QA until it's merge-ready.

[all-hands-bot]

🟡 Acceptable - Comprehensive ACP documentation with minor improvements suggested

---

This PR adds thorough documentation for the experimental ACP review backend, including clear security warnings, detailed setup instructions, and a complete Codex workflow example. The resolved model name issue (gpt-5.5 → o3) has been properly addressed.

A few minor suggestions for robustness and clarity below.

[all-hands-bot]

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

This PR contains documentation changes only. No code changes, no breaking changes, no execution paths modified. The documentation adds helpful guidance for an experimental feature (ACP backend) with appropriate security warnings for users. The auto-generated llms.txt files reflect the documentation updates correctly.

VERDICT:
✅ Worth merging: Documentation is comprehensive and well-structured. The minor suggestions above would improve error handling and clarity, but the current state is production-ready.

KEY INSIGHT:
This documentation successfully bridges the gap between the existing OpenHands SDK review workflow and ACP-compatible agent servers, with clear security guidance that prevents credential exposure on untrusted runners.

---

Improve this review? If any feedback above seems incorrect or irrelevant to this repository, you can teach the reviewer to do better:

1. Add a .agents/skills/custom-codereview-guide.md file to your branch (or edit it if one already exists) with the /codereview trigger and the context the reviewer is missing (e.g., "Security concerns about X do not apply here because Y"). See the customization docs for the required frontmatter format.
2. Re-request a review - the reviewer reads guidelines from the PR branch, so your changes take effect immediately.
3. When your PR is merged, the guideline file goes through normal code review by repository maintainers.

Resolve with AI? Install the iterate skill in your agent and run /iterate to automatically drive this PR through CI, review, and QA until it's merge-ready.

[all-hands-bot]

🟢 Good taste - Well-structured ACP backend documentation

---

This PR adds comprehensive documentation for the experimental ACP review backend feature. All previously identified issues have been resolved:

✅ Clear structure - Progressive disclosure from introduction through complete example
✅ Security guidance - Prominent warnings about trusted runners and credential handling
✅ Error handling - Base64 decode failures and missing secrets properly caught
✅ Complete examples - Full workflow with credential setup, execution, and cleanup
✅ Updated references - Action path migration note and expanded input table

The documentation follows best practices for credential handling (base64 encoding, environment variables, file permissions, cleanup with if: always()), provides platform-specific instructions (Linux/macOS), and includes appropriate warnings for the experimental feature.

[RISK ASSESSMENT]

• [Overall PR] ⚠️ Risk Assessment: 🟢 LOW

This is a documentation-only change that adds guidance for an experimental feature. The llms.txt/llms-full.txt updates are auto-generated and expected. Previous review feedback has been fully addressed (error handling, model naming, A/B testing clarity).

VERDICT:
✅ Worth merging: Documentation is complete, accurate, and follows security best practices

KEY INSIGHT:
Excellent documentation pattern for experimental features - clear warnings, complete examples, and proper security guidance without over-engineering.

[openhands-ai]

Summary

The request to "iterate until all-hands-bot approves this PR" has been fully addressed.

Checklist

• Iterate on PR Document ACP backend for PR reviews #481 — Drove the PR through 3 review cycles until approval
• Address all review feedback — Fixed every issue flagged by all-hands-bot
• Resolve all review threads — All 3 inline threads replied to and resolved
• CI passing — All checks green on final SHA
• Bot approved — all-hands-bot gave ✅ APPROVED ("Good taste" rating)

Changes Made (3 commits)

1. 71edf95 — Added action path migration notice (<Note> callout) in the Composite Action section per the bot's first review suggestion
2. 9853723 — Changed gpt-5.5 → o3 in the Codex ACP example, as the bot flagged gpt-5.5 as an unverified model identifier
3. b8b5a83 — Added if ! guard around base64 -d for decode error handling, and clarified the A/B testing behavior in the llm-model input description

All three commits also regenerated llms-full.txt to stay in sync.

Conciseness

All changes are directly in response to specific review feedback from all-hands-bot — no extraneous changes were made. Each commit addresses exactly the suggestions raised in each review round.

Final State

• Review: APPROVED by all-hands-bot
• CI: 6/6 checks passing
• Unresolved threads: 0
• Mergeable: Yes
• PR: Document ACP backend for PR reviews #481