Create a review comment for a pull request

POST

/repos/{owner}/{repo}/pulls/{pull_number}/comments

Creates a review comment on the diff of a specified pull request. To add a regular comment to a pull request timeline, see “Create an issue comment.”

If your comment applies to more than one line in the pull request diff, you should use the parameters line, side, and optionally start_line and start_side in your request.

The position parameter is closing down. If you use position, the line, side, start_line, and start_side parameters are not required.

This endpoint triggers notifications. Creating content too quickly using this endpoint may result in secondary rate limiting. For more information, see “Rate limits for the API” and “Best practices for using the REST API.”

This endpoint supports the following custom media types. For more information, see “Media types.”

application/vnd.github-commitcomment.raw+json: Returns the raw markdown body. Response will include body. This is the default if you do not pass any specific media type.
application/vnd.github-commitcomment.text+json: Returns a text only representation of the markdown body. Response will include body_text.
application/vnd.github-commitcomment.html+json: Returns HTML rendered from the body’s markdown. Response will include body_html.
application/vnd.github-commitcomment.full+json: Returns raw, text, and HTML representations. Response will include body, body_text, and body_html.

API method documentation

Parameters

Path Parameters

owner

required

string

The account owner of the repository. The name is not case sensitive.

repo

required

string

The name of the repository without the .git extension. The name is not case sensitive.

pull_number

required

integer

The number that identifies the pull request.

Request Body^required

application/json

object

body

required

The text of the review comment.

string

commit_id

required

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.

string

path

required

The relative path to the file that necessitates a comment.

string

position

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.

integer

side

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” in the GitHub Help documentation.

string

Allowed values: LEFT RIGHT

line

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.

integer

start_line

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” in the GitHub Help documentation.

integer

start_side

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” in the GitHub Help documentation. See side in this table for additional context.

string

Allowed values: LEFT RIGHT side

in_reply_to

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”. When specified, all parameters other than body in the request body are ignored.

integer

subject_type

The level at which the comment is targeted.

string

Allowed values: line file

Examples

example-for-a-multi-line-comment

Example for a multi-line comment

{
  "body": "Great stuff!",
  "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "path": "file1.txt",
  "start_line": 1,
  "start_side": "RIGHT",
  "line": 2,
  "side": "RIGHT"
}

Responses

201

Response

application/json

Pull Request Review Comment

Pull Request Review Comments are comments on a portion of the Pull Request’s diff.

object

url

required

URL for the pull request review comment

string

pull_request_review_id

required

The ID of the pull request review to which the comment belongs.

integer format: int64

nullable

required

The ID of the pull request review comment.

integer format: int64

node_id

required

The node ID of the pull request review comment.

string

diff_hunk

required

The diff of the line that the comment refers to.

string

path

required

The relative path of the file to which the comment applies.

string

position

The line index in the diff to which the comment applies. This field is closing down; use line instead.

integer

original_position

The index of the original line in the diff to which the comment applies. This field is closing down; use original_line instead.

integer

commit_id

required

The SHA of the commit to which the comment applies.

string

original_commit_id

required

The SHA of the original commit to which the comment applies.

string

in_reply_to_id

The comment ID to reply to.

integer

user

required

Simple User

A GitHub user.

object

name

string

nullable

email

string

nullable

login

required

string

required

integer format: int64

node_id

required

string

avatar_url

required

string format: uri

gravatar_id

required

string

nullable

url

required

string format: uri

html_url

required

string format: uri

followers_url

required

string format: uri

following_url

required

string

gists_url

required

string

starred_url

required

string

subscriptions_url

required

string format: uri

organizations_url

required

string format: uri

repos_url

required

string format: uri

events_url

required

string

received_events_url

required

string format: uri

type

required

string

site_admin

required

boolean

starred_at

string

user_view_type

string

body

required

The text of the comment.

string

created_at

required

string format: date-time

updated_at

required

string format: date-time

html_url

required

HTML URL for the pull request review comment.

string format: uri

pull_request_url

required

URL for the pull request that the review comment belongs to.

string format: uri

author_association

required

author_association

How the author is associated with the repository.

string

Allowed values: COLLABORATOR CONTRIBUTOR FIRST_TIMER FIRST_TIME_CONTRIBUTOR MANNEQUIN MEMBER NONE OWNER

_links

required

object

self

required

object

href

required

string format: uri

html

required

object

href

required

string format: uri

pull_request

required

object

href

required

string format: uri

start_line

The first line of the range for a multi-line comment.

integer

nullable

original_start_line

The first line of the range for a multi-line comment.

integer

nullable

start_side

The side of the first line of the range for a multi-line comment.

string

default: RIGHT nullable

Allowed values: LEFT RIGHT

line

The line of the blob to which the comment applies. The last line of the range for a multi-line comment

integer

original_line

The line of the blob to which the comment applies. The last line of the range for a multi-line comment

integer

side

The side of the diff to which the comment applies. The side of the last line of the range for a multi-line comment

string

default: RIGHT

Allowed values: LEFT RIGHT

subject_type

The level at which the comment is targeted, can be a diff line or a file.

string

Allowed values: line file

reactions

Reaction Rollup

object

url

required

string format: uri

total_count

required

integer

required

integer

-1

required

integer

laugh

required

integer

confused

required

integer

heart

required

integer

hooray

required

integer

eyes

required

integer

rocket

required

integer

body_html

string

body_text

string

Examples

example-for-a-multi-line-comment

{
  "url": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1",
  "pull_request_review_id": 42,
  "id": 10,
  "node_id": "MDI0OlB1bGxSZXF1ZXN0UmV2aWV3Q29tbWVudDEw",
  "diff_hunk": "@@ -16,33 +16,40 @@ public class Connection : IConnection...",
  "path": "file1.txt",
  "position": 1,
  "original_position": 4,
  "commit_id": "6dcb09b5b57875f334f61aebed695e2e4193db5e",
  "original_commit_id": "9c48853fa3dc5c1c3d6f1f1cd1f2743e72652840",
  "in_reply_to_id": 8,
  "user": {
    "login": "octocat",
    "id": 1,
    "node_id": "MDQ6VXNlcjE=",
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  },
  "body": "Great stuff!",
  "created_at": "2011-04-14T16:00:49Z",
  "updated_at": "2011-04-14T16:00:49Z",
  "html_url": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1",
  "pull_request_url": "https://api.github.com/repos/octocat/Hello-World/pulls/1",
  "author_association": "NONE",
  "_links": {
    "self": {
      "href": "https://api.github.com/repos/octocat/Hello-World/pulls/comments/1"
    },
    "html": {
      "href": "https://github.com/octocat/Hello-World/pull/1#discussion-diff-1"
    },
    "pull_request": {
      "href": "https://api.github.com/repos/octocat/Hello-World/pulls/1"
    }
  },
  "start_line": 1,
  "original_start_line": 1,
  "start_side": "RIGHT",
  "line": 2,
  "original_line": 2,
  "side": "RIGHT"
}

Headers

Location

string

Example

https://api.github.com/repos/octocat/Hello-World/pulls/comments/1

403

Forbidden

application/json

Basic Error

Basic Error

object

message

string

documentation_url

string

url

string

status

string

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "url": "example",
  "status": "example"
}

422

Validation failed, or the endpoint has been spammed.

application/json

Validation Error

Validation Error

object

message

required

string

documentation_url

required

string

errors

Array<object>

object

resource

string

field

string

message

string

code

required

string

index

integer

value

One of:

string

nullable

Example ^generated

{
  "message": "example",
  "documentation_url": "example",
  "errors": [
    {
      "resource": "example",
      "field": "example",
      "message": "example",
      "code": "example",
      "index": 1,
      "value": [
        "example"
      ]
    }
  ]
}

Create a review comment for a pull request

Parameters

Path Parameters

Request Body required

Examples

Responses

201

Examples

Headers

Example

403

Example generated

422

Example generated

Request Body^required

Example ^generated

Example ^generated