GitHub: Create a review comment for a pull request
GitHub pulls.pullsCreateReviewComment: arguments, response, policy and SDK examples.
← Pulls operations · Get started
Operation github.pulls_create_review_comment
Provider route: POST /repos/{owner}/{repo}/pulls/{pull_number}/comments. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { GitHubIntegration } from "@alter-ai/github";
async function execute(input: Parameters<GitHubIntegration["pulls"]["pullsCreateReviewComment"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.pulls.pullsCreateReviewComment(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_github import GitHubIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.pulls.pulls_create_review_comment(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.owner | string | Required within parent | |
path.repo | string | Required within parent | |
path.pull_number | integer | Required within parent | |
body | object | Required within parent | |
body.body | string | Required within parent | The text of the review comment. |
body.commit_id | string | Required within parent | The SHA of the commit needing a comment. Not using the latest commit SHA may render your comment outdated if a subsequent commit modifies the line you specify as the `position`. |
body.in_reply_to | integer | Optional | The ID of the review comment to reply to. To find the ID of a review comment with [“List review comments on a pull request”](#list-review-comments-on-a-pull-request). When specified, all parameters other than `body` in the request body are ignored. |
body.line | integer | Optional | Required unless using `subject_type:file`. The line of the blob in the pull request diff that the comment applies to. For a multi-line comment, the last line of the range that your comment applies to. |
body.path | string | Required within parent | The relative path to the file that necessitates a comment. |
body.position | integer | Optional | This parameter is closing down. Use `line` instead. The position in the diff where you want to add a review comment. Note this value is not the same as the line number in the file. The position value equals the number of lines down from the first ”@@” hunk header in the file you want to add a comment. The line just below the ”@@” line is position 1, the next line is position 2, and so on. The position in the diff continues to increase through lines of whitespace and additional hunks until the beginning of a new file. |
body.side | string | Optional | In a split diff view, the side of the diff that the pull request’s changes appear on. Can be `LEFT` or `RIGHT`. Use `LEFT` for deletions that appear in red. Use `RIGHT` for additions that appear in green or unchanged lines that appear in white and are shown for context. For a multi-line comment, side represents whether the last line of the comment range is a deletion or addition. For more information, see “[Diff view options](https://docs.github.com/articles/about-comparing-branches-in-pull-requests#diff-view-options)” in the GitHub Help documentation. One of: LEFT, RIGHT |
body.start_line | integer | Optional | Required when using multi-line comments unless using `in_reply_to`. The `start_line` is the first line in the pull request diff that your multi-line comment applies to. To learn more about multi-line comments, see “[Commenting on a pull request](https://docs.github.com/articles/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request)” in the GitHub Help documentation. |
body.start_side | string | Optional | Required when using multi-line comments unless using `in_reply_to`. The `start_side` is the starting side of the diff that the comment applies to. Can be `LEFT` or `RIGHT`. To learn more about multi-line comments, see “[Commenting on a pull request](https://docs.github.com/articles/commenting-on-a-pull-request#adding-line-comments-to-a-pull-request)” in the GitHub Help documentation. See `side` in this table for additional context. One of: LEFT, RIGHT, side |
body.subject_type | string | Optional | The level at which the comment is targeted. One of: line, file |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Create a reply for a review comment — response body |
Referenced models: Create a reply for a review comment — response body
Schemas
Section titled “Schemas”1 more schema is linked from the tables above, on the schema pages.
Create a reply for a review comment — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Pull Request Review Comments are comments on a portion of the Pull Request's diff. |
_links | object | Required within parent | |
_links.html | object | Required within parent | |
_links.html.href | string | Required within parent | Format: uri |
_links.pull_request | object | Required within parent | |
_links.pull_request.href | string | Required within parent | Format: uri |
_links.self | object | Required within parent | |
_links.self.href | string | Required within parent | Format: uri |
author_association | string | Required within parent | How the author is associated with the repository. Known values: COLLABORATOR, CONTRIBUTOR, FIRST_TIMER, FIRST_TIME_CONTRIBUTOR, MANNEQUIN, MEMBER, NONE, OWNER |
body | string | Required within parent | The text of the comment. |
body_html | string | Optional | |
body_text | string | Optional | |
commit_id | string | Required within parent | The SHA of the commit to which the comment applies. |
created_at | string | Required within parent | Format: date-time |
diff_hunk | string | Required within parent | The diff of the line that the comment refers to. |
html_url | string | Required within parent | HTML URL for the pull request review comment. Format: uri |
id | JSON | Required within parent | |
id (anyOf 1) | integer | Alternative | The ID of the pull request review comment. Format: int64 |
id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
in_reply_to_id | JSON | Optional | |
in_reply_to_id (anyOf 1) | integer | Alternative | The comment ID to reply to. |
in_reply_to_id (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
line | JSON | Optional | |
line (anyOf 1) | integer | Alternative | The line of the blob to which the comment applies. The last line of the range for a multi-line comment |
line (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
node_id | string | Required within parent | The node ID of the pull request review comment. |
original_commit_id | string | Required within parent | The SHA of the original commit to which the comment applies. |
original_line | JSON | Optional | |
original_line (anyOf 1) | integer | Alternative | The line of the blob to which the comment applies. The last line of the range for a multi-line comment |
original_line (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
original_position | JSON | Optional | |
original_position (anyOf 1) | integer | Alternative | The index of the original line in the diff to which the comment applies. This field is closing down; use `original_line` instead. |
original_position (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
original_start_line | JSON | Optional | |
original_start_line (anyOf 1) | JSON | Alternative | |
original_start_line (anyOf 1) (anyOf 1) | integer | Alternative | The first line of the range for a multi-line comment. |
original_start_line (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
original_start_line (anyOf 2) | null | Alternative | |
path | string | Required within parent | The relative path of the file to which the comment applies. |
position | JSON | Optional | |
position (anyOf 1) | integer | Alternative | The line index in the diff to which the comment applies. This field is closing down; use `line` instead. |
position (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
pull_request_review_id | JSON | Required within parent | |
pull_request_review_id (anyOf 1) | JSON | Alternative | |
pull_request_review_id (anyOf 1) (anyOf 1) | integer | Alternative | The ID of the pull request review to which the comment belongs. Format: int64 |
pull_request_review_id (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
pull_request_review_id (anyOf 2) | null | Alternative | |
pull_request_url | string | Required within parent | URL for the pull request that the review comment belongs to. Format: uri |
reactions | Model | Optional | Expand Get an issue — response body — reactions |
side | string | Optional | The side of the diff to which the comment applies. The side of the last line of the range for a multi-line comment Known values: LEFT, RIGHT Default: RIGHT |
start_line | JSON | Optional | |
start_line (anyOf 1) | JSON | Alternative | |
start_line (anyOf 1) (anyOf 1) | integer | Alternative | The first line of the range for a multi-line comment. |
start_line (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
start_line (anyOf 2) | null | Alternative | |
start_side | JSON | Optional | |
start_side (anyOf 1) | string | Alternative | The side of the first line of the range for a multi-line comment. Known values: LEFT, RIGHT Default: RIGHT |
start_side (anyOf 2) | null | Alternative | |
subject_type | string | Optional | The level at which the comment is targeted, can be a diff line or a file. Known values: line, file |
updated_at | string | Required within parent | Format: date-time |
url | string | Required within parent | URL for the pull request review comment |
user | Model | Required within parent | Expand Get an issue — response body — user |
Referenced models: Get an issue — response body — user, Get an issue — response body — reactions
Get an issue — response body — user
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | |
$ (anyOf 1) | Model | Alternative | Expand Get an issue — response body — user A Git Hub user |
$ (anyOf 2) | null | Alternative |
Referenced models: Get an issue — response body — user A Git Hub user
Get an issue — response body — reactions
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
+1 | JSON | Required within parent | |
+1 (anyOf 1) | integer | Alternative | |
+1 (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
-1 | JSON | Required within parent | |
-1 (anyOf 1) | integer | Alternative | |
-1 (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
confused | JSON | Required within parent | |
confused (anyOf 1) | integer | Alternative | |
confused (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
eyes | JSON | Required within parent | |
eyes (anyOf 1) | integer | Alternative | |
eyes (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
heart | JSON | Required within parent | |
heart (anyOf 1) | integer | Alternative | |
heart (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
hooray | JSON | Required within parent | |
hooray (anyOf 1) | integer | Alternative | |
hooray (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
laugh | JSON | Required within parent | |
laugh (anyOf 1) | integer | Alternative | |
laugh (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
rocket | JSON | Required within parent | |
rocket (anyOf 1) | integer | Alternative | |
rocket (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
total_count | JSON | Required within parent | |
total_count (anyOf 1) | integer | Alternative | |
total_count (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
url | string | Required within parent | Format: uri |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: github.pulls_create_review_comment. Catalog operation: pulls/create-review-comment. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}