From f70256e4fa86bf5ba7ae1555dfbcca47a8fa2f6a Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 29 Apr 2026 19:34:42 +0000 Subject: [PATCH 1/3] Require PR review completion comments --- skills/github-pr-review/README.md | 78 ++++++++++++++++++++++--------- skills/github-pr-review/SKILL.md | 27 +++++++++-- 2 files changed, 79 insertions(+), 26 deletions(-) diff --git a/skills/github-pr-review/README.md b/skills/github-pr-review/README.md index 9735cabf..c2d5d3a8 100644 --- a/skills/github-pr-review/README.md +++ b/skills/github-pr-review/README.md @@ -20,25 +20,57 @@ Bundle ALL comments into a **single review API call**. Do not post comments indi ## Posting a Review -Use the GitHub CLI (`gh`). The `GITHUB_TOKEN` is automatically available. +Use the GitHub CLI (`gh`) with a JSON input file. The `GITHUB_TOKEN` is automatically available. + +**Important**: Always use `--input` with a JSON file instead of `-F` flags. This avoids shell quoting issues with special characters in comment bodies (quotes, backticks, newlines, etc.) and eliminates the need for complex heredoc scripts. + +### Step 1: Create a JSON file ```bash -gh api \ - -X POST \ - repos/{owner}/{repo}/pulls/{pr_number}/reviews \ - -f commit_id='{commit_sha}' \ - -f event='COMMENT' \ - -f body='Brief 1-3 sentence summary.' \ - -f comments[][path]='path/to/file.py' \ - -F comments[][line]=42 \ - -f comments[][side]='RIGHT' \ - -f comments[][body]='🟠 Important: Your comment here.' \ - -f comments[][path]='another/file.js' \ - -F comments[][line]=15 \ - -f comments[][side]='RIGHT' \ - -f comments[][body]='🟡 Suggestion: Another comment.' +cat > /tmp/review.json << 'EOF' +{ + "commit_id": "{commit_sha}", + "event": "COMMENT", + "body": "Brief 1-3 sentence summary.", + "comments": [ + { + "path": "path/to/file.py", + "line": 42, + "side": "RIGHT", + "body": "🟠 Important: Your comment here." + }, + { + "path": "another/file.js", + "line": 15, + "side": "RIGHT", + "body": "🟡 Suggestion: Another comment." + } + ] +} +EOF +``` + +### Step 2: Post the review + +```bash +gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json +``` + +### Step 3: Confirm completion with a PR issue comment + +After the review API call succeeds, always post a short issue comment on the PR conversation confirming that the review was completed. Pull requests are also issues in the GitHub API, so use the issues comments endpoint. + +```bash +gh api -X POST repos/{owner}/{repo}/issues/{pr_number}/comments \ + -f body='Completed OpenHands review: submitted a {COMMENT|APPROVE|REQUEST_CHANGES} review on commit {commit_sha}.' ``` +**Mandatory:** Do not finish without both: +1. creating the PR review object, and +2. posting the completion comment on the PR issue. + +If either API call fails, treat the review as incomplete and continue until it succeeds or surface the failure clearly instead of silently succeeding. + ### Parameters | Parameter | Description | @@ -137,9 +169,13 @@ curl -X POST \ ## Summary -1. Analyze the code and identify issues -2. Post **ONE** review with all inline comments bundled -3. Use priority labels (🔴🟠🟡🟢) on every comment -4. Use suggestion syntax for concrete code changes -5. Keep the review body brief (details go in inline comments) -6. If no issues: post a short approval message \ No newline at end of file +1. Analyze the code and identify important issues (minimize nits) +2. Write review data to a JSON file (e.g., `/tmp/review.json`) +3. Post **ONE** review using `gh api --input /tmp/review.json` +4. Post a short PR issue comment confirming the review was completed +5. Use priority labels (🔴🟠🟡) on every comment +6. Do NOT post comments for code that is acceptable — only comment when action is needed +7. Use suggestion syntax for concrete code changes +8. Keep the review body brief (details go in inline comments) +9. If no issues: post a short approval message with no inline comments +10. Do not finish unless both the review object and completion comment were created successfully diff --git a/skills/github-pr-review/SKILL.md b/skills/github-pr-review/SKILL.md index 7ba363cb..2ab016f4 100644 --- a/skills/github-pr-review/SKILL.md +++ b/skills/github-pr-review/SKILL.md @@ -51,6 +51,21 @@ EOF gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json ``` +### Step 3: Confirm completion with a PR issue comment + +After the review API call succeeds, always post a short issue comment on the PR conversation confirming that the review was completed. Pull requests are also issues in the GitHub API, so use the issues comments endpoint. + +```bash +gh api -X POST repos/{owner}/{repo}/issues/{pr_number}/comments \ + -f body='Completed OpenHands review: submitted a {COMMENT|APPROVE|REQUEST_CHANGES} review on commit {commit_sha}.' +``` + +**Mandatory:** Do not finish without both: +1. creating the PR review object, and +2. posting the completion comment on the PR issue. + +If either API call fails, treat the review as incomplete and continue until it succeeds or surface the failure clearly instead of silently succeeding. + ### Parameters | Parameter | Description | @@ -141,8 +156,10 @@ curl -X POST \ 1. Analyze the code and identify important issues (minimize nits) 2. Write review data to a JSON file (e.g., `/tmp/review.json`) 3. Post **ONE** review using `gh api --input /tmp/review.json` -4. Use priority labels (🔴🟠🟡) on every comment -5. Do NOT post comments for code that is acceptable — only comment when action is needed -6. Use suggestion syntax for concrete code changes -7. Keep the review body brief (details go in inline comments) -8. If no issues: post a short approval message with no inline comments +4. Post a short PR issue comment confirming the review was completed +5. Use priority labels (🔴🟠🟡) on every comment +6. Do NOT post comments for code that is acceptable — only comment when action is needed +7. Use suggestion syntax for concrete code changes +8. Keep the review body brief (details go in inline comments) +9. If no issues: post a short approval message with no inline comments +10. Do not finish unless both the review object and completion comment were created successfully From c8e9dc5a344a880f72d67e7c415dba096b25288e Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 29 Apr 2026 19:37:57 +0000 Subject: [PATCH 2/3] Trim github-pr-review note to always post a review --- skills/github-pr-review/README.md | 78 +++++++++---------------------- skills/github-pr-review/SKILL.md | 27 +++-------- 2 files changed, 28 insertions(+), 77 deletions(-) diff --git a/skills/github-pr-review/README.md b/skills/github-pr-review/README.md index c2d5d3a8..38aef1fd 100644 --- a/skills/github-pr-review/README.md +++ b/skills/github-pr-review/README.md @@ -20,56 +20,26 @@ Bundle ALL comments into a **single review API call**. Do not post comments indi ## Posting a Review -Use the GitHub CLI (`gh`) with a JSON input file. The `GITHUB_TOKEN` is automatically available. - -**Important**: Always use `--input` with a JSON file instead of `-F` flags. This avoids shell quoting issues with special characters in comment bodies (quotes, backticks, newlines, etc.) and eliminates the need for complex heredoc scripts. - -### Step 1: Create a JSON file - -```bash -cat > /tmp/review.json << 'EOF' -{ - "commit_id": "{commit_sha}", - "event": "COMMENT", - "body": "Brief 1-3 sentence summary.", - "comments": [ - { - "path": "path/to/file.py", - "line": 42, - "side": "RIGHT", - "body": "🟠 Important: Your comment here." - }, - { - "path": "another/file.js", - "line": 15, - "side": "RIGHT", - "body": "🟡 Suggestion: Another comment." - } - ] -} -EOF -``` - -### Step 2: Post the review +Use the GitHub CLI (`gh`). The `GITHUB_TOKEN` is automatically available. ```bash -gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json -``` - -### Step 3: Confirm completion with a PR issue comment - -After the review API call succeeds, always post a short issue comment on the PR conversation confirming that the review was completed. Pull requests are also issues in the GitHub API, so use the issues comments endpoint. - -```bash -gh api -X POST repos/{owner}/{repo}/issues/{pr_number}/comments \ - -f body='Completed OpenHands review: submitted a {COMMENT|APPROVE|REQUEST_CHANGES} review on commit {commit_sha}.' +gh api \ + -X POST \ + repos/{owner}/{repo}/pulls/{pr_number}/reviews \ + -f commit_id='{commit_sha}' \ + -f event='COMMENT' \ + -f body='Brief 1-3 sentence summary.' \ + -f comments[][path]='path/to/file.py' \ + -F comments[][line]=42 \ + -f comments[][side]='RIGHT' \ + -f comments[][body]='🟠 Important: Your comment here.' \ + -f comments[][path]='another/file.js' \ + -F comments[][line]=15 \ + -f comments[][side]='RIGHT' \ + -f comments[][body]='🟡 Suggestion: Another comment.' ``` -**Mandatory:** Do not finish without both: -1. creating the PR review object, and -2. posting the completion comment on the PR issue. - -If either API call fails, treat the review as incomplete and continue until it succeeds or surface the failure clearly instead of silently succeeding. +**Mandatory:** Always submit a PR review object before finishing. If you found no actionable issues, post a short `APPROVE` review rather than ending silently without posting a review. ### Parameters @@ -169,13 +139,9 @@ curl -X POST \ ## Summary -1. Analyze the code and identify important issues (minimize nits) -2. Write review data to a JSON file (e.g., `/tmp/review.json`) -3. Post **ONE** review using `gh api --input /tmp/review.json` -4. Post a short PR issue comment confirming the review was completed -5. Use priority labels (🔴🟠🟡) on every comment -6. Do NOT post comments for code that is acceptable — only comment when action is needed -7. Use suggestion syntax for concrete code changes -8. Keep the review body brief (details go in inline comments) -9. If no issues: post a short approval message with no inline comments -10. Do not finish unless both the review object and completion comment were created successfully +1. Analyze the code and identify issues +2. Post **ONE** review with all inline comments bundled +3. Use priority labels (🔴🟠🟡🟢) on every comment +4. Use suggestion syntax for concrete code changes +5. Keep the review body brief (details go in inline comments) +6. If no issues: post a short approval message \ No newline at end of file diff --git a/skills/github-pr-review/SKILL.md b/skills/github-pr-review/SKILL.md index 2ab016f4..dae48c2a 100644 --- a/skills/github-pr-review/SKILL.md +++ b/skills/github-pr-review/SKILL.md @@ -51,20 +51,7 @@ EOF gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json ``` -### Step 3: Confirm completion with a PR issue comment - -After the review API call succeeds, always post a short issue comment on the PR conversation confirming that the review was completed. Pull requests are also issues in the GitHub API, so use the issues comments endpoint. - -```bash -gh api -X POST repos/{owner}/{repo}/issues/{pr_number}/comments \ - -f body='Completed OpenHands review: submitted a {COMMENT|APPROVE|REQUEST_CHANGES} review on commit {commit_sha}.' -``` - -**Mandatory:** Do not finish without both: -1. creating the PR review object, and -2. posting the completion comment on the PR issue. - -If either API call fails, treat the review as incomplete and continue until it succeeds or surface the failure clearly instead of silently succeeding. +**Mandatory:** Always submit a PR review object before finishing. If you found no actionable issues, post a short `APPROVE` review rather than ending silently without posting a review. ### Parameters @@ -156,10 +143,8 @@ curl -X POST \ 1. Analyze the code and identify important issues (minimize nits) 2. Write review data to a JSON file (e.g., `/tmp/review.json`) 3. Post **ONE** review using `gh api --input /tmp/review.json` -4. Post a short PR issue comment confirming the review was completed -5. Use priority labels (🔴🟠🟡) on every comment -6. Do NOT post comments for code that is acceptable — only comment when action is needed -7. Use suggestion syntax for concrete code changes -8. Keep the review body brief (details go in inline comments) -9. If no issues: post a short approval message with no inline comments -10. Do not finish unless both the review object and completion comment were created successfully +4. Use priority labels (🔴🟠🟡) on every comment +5. Do NOT post comments for code that is acceptable — only comment when action is needed +6. Use suggestion syntax for concrete code changes +7. Keep the review body brief (details go in inline comments) +8. If no issues: post a short approval message with no inline comments From 08a448e24d08194c077ade62e9ea4abdd3b25530 Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 29 Apr 2026 21:01:30 +0000 Subject: [PATCH 3/3] chore: address PR review feedback (#222) Co-authored-by: openhands --- skills/github-pr-review/README.md | 29 ++++++++++++++++++++++++----- skills/github-pr-review/SKILL.md | 31 +++++++++++++++++++++++++------ 2 files changed, 49 insertions(+), 11 deletions(-) diff --git a/skills/github-pr-review/README.md b/skills/github-pr-review/README.md index 38aef1fd..9a1c9832 100644 --- a/skills/github-pr-review/README.md +++ b/skills/github-pr-review/README.md @@ -39,7 +39,24 @@ gh api \ -f comments[][body]='🟡 Suggestion: Another comment.' ``` -**Mandatory:** Always submit a PR review object before finishing. If you found no actionable issues, post a short `APPROVE` review rather than ending silently without posting a review. +### Confirm completion with a PR issue comment + +After the review API call succeeds, post a short issue comment on the PR conversation confirming that the review finished. This gives the PR timeline a durable marker that the review was actually submitted on a specific commit, which is useful when an agent analyzed the PR but might otherwise fail before leaving visible proof that the review API call succeeded. + +```bash +gh api -X POST repos/{owner}/{repo}/issues/{pr_number}/comments \ + -f body='Completed OpenHands review: submitted a COMMENT review on commit {commit_sha}.' +``` + +Replace `COMMENT` with the same value you sent in the review request's `event` field (`COMMENT`, `APPROVE`, or `REQUEST_CHANGES`). Replace `{commit_sha}` with the same SHA you used for `commit_id`. + +**Mandatory:** The review is only complete after both API calls succeed: +1. create the PR review object, and +2. post the completion comment on the PR issue. + +If you found no actionable issues, post a short `APPROVE` review and a matching completion comment rather than ending silently without posting a review. + +If the review API call fails, do not post the completion comment. If the review succeeds but the completion comment fails, tell the user that the review was submitted but completion reporting failed, include the review event and commit SHA in that response, and keep trying or ask for help instead of claiming success. ### Parameters @@ -141,7 +158,9 @@ curl -X POST \ 1. Analyze the code and identify issues 2. Post **ONE** review with all inline comments bundled -3. Use priority labels (🔴🟠🟡🟢) on every comment -4. Use suggestion syntax for concrete code changes -5. Keep the review body brief (details go in inline comments) -6. If no issues: post a short approval message \ No newline at end of file +3. Post a short PR issue comment confirming the review was submitted on the same event and commit SHA +4. Use priority labels (🔴🟠🟡) on every comment +5. Use suggestion syntax for concrete code changes +6. Keep the review body brief (details go in inline comments) +7. If no issues: post a short approval message, then post the matching completion comment +8. Do not finish unless both the review object and completion comment were created successfully \ No newline at end of file diff --git a/skills/github-pr-review/SKILL.md b/skills/github-pr-review/SKILL.md index dae48c2a..e1590339 100644 --- a/skills/github-pr-review/SKILL.md +++ b/skills/github-pr-review/SKILL.md @@ -51,7 +51,24 @@ EOF gh api -X POST repos/{owner}/{repo}/pulls/{pr_number}/reviews --input /tmp/review.json ``` -**Mandatory:** Always submit a PR review object before finishing. If you found no actionable issues, post a short `APPROVE` review rather than ending silently without posting a review. +### Step 3: Confirm completion with a PR issue comment + +After the review API call succeeds, post a short issue comment on the PR conversation confirming that the review finished. This gives the PR timeline a durable marker that the review was actually submitted on a specific commit, which is useful when an agent analyzed the PR but might otherwise fail before leaving visible proof that the review API call succeeded. + +```bash +gh api -X POST repos/{owner}/{repo}/issues/{pr_number}/comments \ + -f body='Completed OpenHands review: submitted a COMMENT review on commit {commit_sha}.' +``` + +Replace `COMMENT` with the same value you sent in the review payload's `event` field (`COMMENT`, `APPROVE`, or `REQUEST_CHANGES`). Replace `{commit_sha}` with the same SHA you used in `commit_id`. + +**Mandatory:** The review is only complete after both API calls succeed: +1. create the PR review object, and +2. post the completion comment on the PR issue. + +If you found no actionable issues, post a short `APPROVE` review and a matching completion comment rather than ending silently without posting a review. + +If the review API call fails, do not post the completion comment. If the review succeeds but the completion comment fails, tell the user that the review was submitted but completion reporting failed, include the review event and commit SHA in that response, and keep trying or ask for help instead of claiming success. ### Parameters @@ -143,8 +160,10 @@ curl -X POST \ 1. Analyze the code and identify important issues (minimize nits) 2. Write review data to a JSON file (e.g., `/tmp/review.json`) 3. Post **ONE** review using `gh api --input /tmp/review.json` -4. Use priority labels (🔴🟠🟡) on every comment -5. Do NOT post comments for code that is acceptable — only comment when action is needed -6. Use suggestion syntax for concrete code changes -7. Keep the review body brief (details go in inline comments) -8. If no issues: post a short approval message with no inline comments +4. Post a short PR issue comment confirming the review was submitted on the same event and commit SHA +5. Use priority labels (🔴🟠🟡) on every comment +6. Do NOT post comments for code that is acceptable - only comment when action is needed +7. Use suggestion syntax for concrete code changes +8. Keep the review body brief (details go in inline comments) +9. If no issues: post a short approval message with no inline comments, then post the matching completion comment +10. Do not finish unless both the review object and completion comment were created successfully