Pull Request¶
A pull request (merge request) merges changes from a source branch into a target branch. Through the API you can create, update, and merge PRs, manage comments and labels, assign reviewers, testers, and mergers, and read changed files, commits, and operation logs.
Repository-level labels and milestones have their own separate groups; this page covers only the PR endpoints themselves.
Objects¶
| Object | Description | Related endpoint |
|---|---|---|
| Pull Request | Title, state, source/target branch, description, milestone, labels, whether it is a draft | Get a single pull request |
| Merge | Three methods: merge / squash / rebase | Merge a pull request |
| Comment | Regular PR comments and line-level/file-level code comments | Submit pull request comments |
| Discussion | The discussion thread a comment belongs to; replies are located by discussion ID | Reply to a pull request comment |
| Label | Labels on a PR; supports adding, replacing, and batch deletion | Replace all labels on a pull request |
| Reviewer | Assign and cancel reviewers, reset review status | Assign users to review a pull request |
| Tester | Assign and cancel testers, reset test status, candidate list | Assign users to test a pull request |
| Merger | Specify one or more mergers | Set the merger of a pull request |
| Linked issue | Bidirectional association between a PR and an issue | Associate a pull request with an issue |
| Changes | The PR's commit list, changed files, and file change statistics | Pull request commit file list |
| Reaction | A user's emoji reaction to a PR and its comments | Get the reactions for a pull request |
| History and logs | Modification history and operation logs of PRs and comments | Get the operation logs for a pull request |
Identification¶
- Repository-level endpoints identify the repository with
owner+repoand identify the PR number withnumber. - Comments are identified by
id(path/pulls/comments/{id}); review comments and replies are identified bydiscussion_idandcomment_id. - Organization-level endpoints use
org, with the path/api/v5/org/{org}/pull_requests(singularorg). - Enterprise-level endpoints use
enterprise; list endpoint paths use*as a placeholder.
Common tasks¶
| Task | Endpoint |
|---|---|
| Create a pull request | POST /api/v5/repos/{owner}/{repo}/pulls |
| List repository PRs | GET /api/v5/repos/{owner}/{repo}/pulls |
| Get a single PR | GET /api/v5/repos/{owner}/{repo}/pulls/{number} |
| Update a PR | PATCH /api/v5/repos/{owner}/{repo}/pulls/{number} |
| Merge a PR | PUT /api/v5/repos/{owner}/{repo}/pulls/{number}/merge |
| Check whether it is merged | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/merge |
| List changed files | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/files |
| Submit a comment | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/comments |
| Assign reviewers | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/assignees |
| Assign testers | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/testers |
| Set mergers | PUT /api/v5/repos/{owner}/{repo}/pulls/{number}/mergers |
Notes¶
- The organization-level PR list path is
GET /api/v5/org/{org}/pull_requests, using the singularorg, which differs from other/orgs/{org}/…endpoints; the enterprise-level list usesGET /api/v5/enterprises/*/pull_requests, with*as a placeholder in the path. - Comments have two kinds of paths:
/pulls/{number}/comments, operated by PR (supports line-level and file-level comments), and/pulls/comments/{id}, operated by comment ID. - Replying to a comment requires the discussion ID:
POST /pulls/{number}/discussions/{discussion_id}/comments; to change the resolved status of a review comment, usePUT /pulls/{number}/comments/{discussion_id}, where the path carriesdiscussion_idrather than the comment ID. - There are two coexisting sets of review-related endpoints:
/pulls/{number}/assigneesand/pulls/{number}/reviewers; the former carries the semantics of resetting review status, and the latter is the reviewer list. Check the parameter table on the specific endpoint page before calling. - Candidate list paths are inconsistent: the tester candidates are
GET /pulls/option_testers(without a PR number), while the reviewer candidates areGET /pulls/{number}/option_reviewers. - File changes have two kinds of responses:
/pulls/{number}/filesreturns the list of changed files, and/pulls/{number}/files.jsonreturns change statistics and diff references.
Endpoint list¶
This module has 45 endpoints.
| # | Endpoint | Method and path | Description |
|---|---|---|---|
| 1 | Get the project pull request list | GET /api/v5/repos/{owner}/{repo}/pulls |
This endpoint retrieves the list of pull requests in the specified repository and supports filtering by state, target branch, time range, sorting, pagination, and other conditions… |
| 2 | Create a pull request | POST /api/v5/repos/{owner}/{repo}/pulls |
This endpoint creates a pull request (merge request) in the specified repository. You can set the title, source and target branches, and description, and optionally specify… |
| 3 | Merge a pull request | PUT /api/v5/repos/{owner}/{repo}/pulls/{number}/merge |
This endpoint merges the pull request with the specified number in the specified repository. It supports merging by merge, squash, or rebase… |
| 4 | Check whether a pull request is merged | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/merge |
This endpoint checks whether a pull request in the specified repository has been merged, locating the target by repository namespace address, repository path, and PR number… |
| 5 | Get the issues associated with a PR | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/issues |
This endpoint retrieves the list of issues associated with a pull request (PR) in the specified repository and returns each issue's… |
| 6 | Submit pull request comments | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/comments |
This endpoint submits a comment to the specified pull request. You can specify a file path and line number for a line-level comment, or choose a file-level comment… |
| 7 | Get all comments of a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/comments |
This endpoint retrieves all comments of a pull request in the specified repository, supports filtering by code-line comments and regular PR comment types, and can… |
| 8 | Pull request commit file list | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/files |
This endpoint queries the list of files involved in the changes of a pull request (merge request) in the specified repository, returning each changed file's path, state… |
| 9 | Update pull request information | PATCH /api/v5/repos/{owner}/{repo}/pulls/{number} |
This endpoint updates the information of a pull request in the specified repository, supporting changes to the title, content, state, milestone, labels, draft status, and more… |
| 10 | Get a single pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number} |
This endpoint retrieves the details of a single pull request in the specified repository, including the title, state, reviewer and tester information, labels, merge gate… |
| 11 | Get all commit information for a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/commits |
This endpoint retrieves all commit information for a pull request in the specified repository, returning the commit SHA, commit… |
| 12 | Create a pull request label | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/labels |
This endpoint creates labels for the specified pull request in the specified repository by submitting an array of label names in the request body; on success you can retrieve the created labels… |
| 13 | Get all labels of a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/labels |
This endpoint retrieves all labels of a pull request in the specified repository, locating the target by repository namespace address, repository path, and PR number… |
| 14 | Replace all labels on a pull request | PUT /api/v5/repos/{owner}/{repo}/pulls/{number}/labels |
This endpoint replaces all labels of the specified pull request. The request body is an array of label names; once submitted, it overwrites that pull request… |
| 15 | Delete pull request labels | DELETE /api/v5/repos/{owner}/{repo}/pulls/{number}/labels/{name} |
This endpoint deletes one or more labels from the specified pull request in the specified repository, supporting batch deletion by separating label names with English commas… |
| 16 | Handle pull request testing | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/test |
This endpoint handles the test operation for a pull request in the specified repository, supporting a forced test pass via the force parameter (this capability is only… |
| 17 | Handle pull request approval | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/review |
This endpoint performs approval handling for the pull request with the specified number in the specified repository, advancing the PR's review process by submitting a review request… |
| 18 | Get the operation logs for a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/operate_logs |
This endpoint queries the operation logs of a pull request in the specified repository, supports reverse-chronological ordering and paginated browsing, and returns details of each operation… |
| 19 | Reset the status of a pull request test | PATCH /api/v5/repos/{owner}/{repo}/pulls/{number}/testers |
This endpoint resets the test status of the specified pull request. Through the reset_all parameter in the request body, you can reset a single tester… |
| 20 | Assign users to test a pull request | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/testers |
This endpoint assigns testers to a pull request in the specified repository, setting them through the tester list in the request body, and supporting overwrite updates… |
| 21 | Cancel user testing of a pull request | DELETE /api/v5/repos/{owner}/{repo}/pulls/{number}/testers |
This endpoint cancels a test user of a pull request in the specified repository. By passing the personal namespace address of the user to remove, you can remove the corresponding tester… |
| 22 | Get the list of people who can be testers for a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/option_testers |
This endpoint retrieves the list of users in the specified repository who can be testers of a pull request, returning each candidate's account, nickname, avatar, and object identifier… |
| 23 | Reset the status of a pull request review | PATCH /api/v5/repos/{owner}/{repo}/pulls/{number}/assignees |
This endpoint resets the review status of a specific pull request in the specified repository; an optional parameter in the request body sets whether to reset the review status of all reviewers… |
| 24 | Assign users to review a pull request | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/assignees |
This endpoint assigns review users to the specified pull request in the specified repository: by submitting a comma-separated list of user personal namespace addresses, you can assign one… |
| 25 | Cancel user review of a pull request | DELETE /api/v5/repos/{owner}/{repo}/pulls/{number}/assignees |
This endpoint cancels the assigned user review on the specified pull request, withdraws the user's review qualification, and removes their review task so that the user no longer participates… |
| 26 | File change information submitted by a PR | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/files.json |
This endpoint queries the file change information submitted by the specified PR, returning the number of changed files, added and deleted lines, commit information referenced for comparison, and… |
| 27 | Enterprise pull request list | GET /api/v5/enterprises/*/pull_requests |
This endpoint queries the list of pull requests under the specified enterprise (namespace), supporting conditions such as state, author, target branch, labels, and time range… |
| 28 | Get a comment of a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/comments/{id} |
This endpoint retrieves the details of a comment of a pull request in the specified repository by comment ID, including the comment content, author information, creation and update… |
| 29 | Edit a comment | PATCH /api/v5/repos/{owner}/{repo}/pulls/comments/{id} |
This endpoint edits the content of a comment under the specified pull request in the repository, locating the target comment by comment ID and submitting new comment content… |
| 30 | Delete a comment | DELETE /api/v5/repos/{owner}/{repo}/pulls/comments/{id} |
This endpoint deletes a comment of the specified pull request in the specified repository, locating the target comment by repository address, repository path, and comment ID, and deleting… |
| 31 | Organization pull request list | GET /api/v5/org/{org}/pull_requests |
This endpoint queries the list of pull requests under the specified organization, supporting filters such as repository, state, target branch, author, labels, and creation and update time range… |
| 32 | Get the pull requests associated with an enterprise issue | GET /api/v5/enterprises/{enterprise}/issues/{number}/pull_requests |
This endpoint retrieves all pull requests associated with an issue under the specified enterprise, locating the target by enterprise path and issue global… |
| 33 | Associate a pull request with an issue | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/issues |
This endpoint associates an issue in the specified repository with the target pull request; the request must submit the list of issue numbers to associate… |
| 34 | Dissociate issues from a pull request | DELETE /api/v5/repos/{owner}/{repo}/pulls/{number}/issues |
This endpoint removes the association between the specified pull request and multiple issues; pass the issue numbers to dissociate in the request body… |
| 35 | Reply to a pull request comment | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/discussions/{discussion_id}/comments |
This endpoint replies to a comment in the discussion of the specified pull request; after the reply body is submitted, the reply is written into the corresponding discussion as a new comment… |
| 36 | Change the resolved status of a review comment | PUT /api/v5/repos/{owner}/{repo}/pulls/{number}/comments/{discussion_id} |
This endpoint changes the resolved status of a review comment (comment/discussion) in the specified pull request, using the resolved parameter in the request body… |
| 37 | Set the merger of a pull request | PUT /api/v5/repos/{owner}/{repo}/pulls/{number}/mergers |
This endpoint sets mergers for a pull request in the specified repository; by submitting comma-separated user personal namespace addresses, you can specify one or more… |
| 38 | Assign a user to review a pull request | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/reviewers |
This endpoint assigns users as reviewers to a pull request in the specified repository, supporting adding or overwrite-updating the reviewer list and returning the assigned… |
| 39 | Cancel user review of a pull request | DELETE /api/v5/repos/{owner}/{repo}/pulls/{number}/reviewers |
This endpoint cancels user reviews of a pull request in the specified repository; by passing the list of user personal namespace addresses whose reviews to cancel, you can… |
| 40 | Get the list of people who can be reviewers for a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/option_reviewers |
This endpoint retrieves the list of selectable reviewers for the specified pull request in the specified repository, returning each reviewer's user ID, account, nickname, avatar, and more… |
| 41 | Get the reactions for a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/user_reactions |
This endpoint retrieves the reaction list of the specified pull request in the specified repository, returning the emoji and reacting user information for each reaction… |
| 42 | Get the reactions for a pull request comment | GET /api/v5/repos/{owner}/{repo}/pulls/comment/{comment_id}/user_reactions |
This endpoint retrieves the reaction list of the specified pull request comment, returning each reaction record's number, emoji, and reacting user information, and supporting filtering by emoji… |
| 43 | Get the modification history of a pull request | GET /api/v5/repos/{owner}/{repo}/pulls/{number}/modify_history |
This endpoint retrieves the modification history of the specified pull request in the specified repository, returning the modification time, modified content, operator, updater, and user information… |
| 44 | Get the modification history of pull request comments | GET /api/v5/repos/{owner}/{repo}/pulls/comment/{comment_id}/modify_history |
This endpoint retrieves the modification history of pull request comments in the specified repository. Through this endpoint, users can view a comment's creation and successive modifications… |
| 45 | Refresh pull request comment position/expiration status | POST /api/v5/repos/{owner}/{repo}/pulls/{number}/refresh_position |
This endpoint refreshes the position and expiration status of the specified pull request comments, supporting targeted refresh by file path or comment ID; when neither is provided… |
Markdown source: View on AtomGit·Content from the open-source project gitcode-dev/atomgit-api-doc