Open a pull request
Propose merging one branch into another, as a draft or ready for review, and edit its title and description.
A pull request carries reviews, comments, checks and an approval count. Issues and pull requests
share one numbering per repository. The examples use the repository id
5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 and the branch add-hint-counter.
Prerequisites
- Both branches pushed to the repository, and different from each other. Otherwise the API answers
400
Source and target branches must differorOne of those branches does not exist. - Permission for
git:CreatePullRequest. - In the Deutsche Cloud Console, also
git:GetRepositoryto open the repository's pages (without it the page is not found). - In the Deutsche Cloud Console, New pull request is not shown while the repository is archived, is a mirror, or is still importing.
Open it
- In the repository, choose Pull requests, then New pull request.
- Under Branches, pick the Source branch add-hint-counter and the Target branch (the repository's default branch unless you change it).
- Enter a Title and, optionally, a Description.
- (Optional) Select Open as draft.
- Choose Create pull request (or Create draft pull request). The pull request's page opens.
dcloud git pulls create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
--title "Show clue count" --source-branch add-hint-counter --target-branch mainAdd --is-draft to open it as a draft.
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls
{ "title": "Show clue count", "sourceBranch": "add-hint-counter", "targetBranch": "main", "isDraft": false }Result
The response carries the merge status (mergeStatus):
mergeStatus |
Meaning |
|---|---|
mergeable |
can be merged |
conflicted |
has conflicts with the target |
up_to_date |
nothing to merge |
unknown |
cannot be computed: a branch is missing |
Opening a pull request, a draft too, starts the on: pull_request workflows and asks the code
owners of the changed files for a review.
Drafts
A draft cannot be merged, given auto-merge or added to the merge queue until it is marked ready. It can be reviewed and commented on like an open pull request.
Marking a draft ready, or turning an open pull request back into a draft, needs
git:UpdatePullRequest. In the Deutsche Cloud Console, opening the pull request also needs git:GetRepository
and git:GetPullRequest (without either the page is not found).
- Open the pull request. A draft says This pull request is still a draft. in the merge box.
- Choose Ready for review. The pull request is open.
To turn an open pull request back into a draft, choose Convert to draft in the merge box.
The buttons are shown only with git:UpdatePullRequest, and not in an archived repository or a
mirror, where the API refuses as well (see below). On a pull request whose target branch requires
the merge queue, the merge box and with it these controls is not shown; use the CLI or API there.
dcloud git pulls ready 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7
dcloud git pulls convert-to-draft 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 7POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/readyPOST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/pulls/7/draftThe pull request's timeline records who changed it. Marking it ready sends the ready_for_review
webhook event and converting it sends converted_to_draft; workflows start only if they list that
type under on.pull_request.types. Asking for the state it already has answers 200 and changes
nothing.
Refused with 409:
The pull request is closedorThe pull request is merged.Repository is archived.- In a mirror:
This repository is a mirror of …; review and merge its pull requests on ….
Pull request states
| State | Meaning |
|---|---|
draft |
a draft; cannot be merged until marked ready |
open |
ready for review |
merged |
merged; the merge commit is on the target branch |
closed |
closed without merging; can be reopened |
Close pull request and Reopen pull request (POST …/pulls/{n}/close, …/reopen) need
git:ClosePullRequest. Closing a merged or closed one answers 409 Pull request is already <state>; reopening one that is not closed, 409 Cannot reopen a pull request that is <state>.
A draft that is closed and reopened is a draft again.
Edit the title or description
Choose Edit next to the title, or Edit in the description's … menu, while the pull
request is open, a draft or closed (PATCH /git/api/repositories/{repoId}/pulls/{n} with title
and/or body; git:UpdatePullRequest). The description is Markdown, and #12 links to issue or
pull request 12. Edits are refused with 409: on a merged pull request (A merged pull request is history), in an archived repository (Repository is archived), and in a mirror, whose pull
requests are the source's.
Related
Related
- POST /git/api/repositories/{repoId}/pulls
- PATCH /git/api/repositories/{repoId}/pulls/{prNumber}
- GET /git/api/repositories/{repoId}/pulls
- GET /git/api/repositories/{repoId}/pulls/{prNumber}
- POST /git/api/repositories/{repoId}/pulls/{prNumber}/ready
- POST /git/api/repositories/{repoId}/pulls/{prNumber}/draft