| 1 | --- |
| 2 | title: Pull requests and checks |
| 3 | description: What the merge box shows before a pull request can merge, the checks your workflows report and which ones a merge needs, reviewers, sessions, how a large change's files load, drafts, closing and reopening, editing and deleting comments, merge methods, commit messages, auto-merge, merging by pushing, closing work items, deleting branches, comments on commits, conflicts, and keeping a branch up to date. |
| 4 | --- |
| 5 | |
| 6 | At the foot of an open pull request's conversation, the **merge box** says |
| 7 | what stands between it and its target branch: its checks, its reviews, |
| 8 | whether it merges cleanly, and the button that merges it. Everything in it |
| 9 | updates by itself while something is still running. |
| 10 | |
| 11 | ## Checks |
| 12 | |
| 13 | A pull request's checks are the statuses reported on its head commit. Most |
| 14 | come from the repository's [workflows](/guides/actions/): every workflow |
| 15 | that runs on `pull_request` runs on every pull request's head, whoever |
| 16 | opened it, and reports a check named after the |
| 17 | workflow. A workflow named `CI` reports the check `CI`; its status context |
| 18 | is `CI / pull_request`, the workflow's name and the event it ran for. Other |
| 19 | parts of g1t report under their own names, such as `g1t / deploy` (or |
| 20 | `g1t / deploy (<project>)`) for a [deployment](/guides/deployments/), and |
| 21 | your own CI and integrations report statuses and check runs through the |
| 22 | API: see [Checks](/guides/checks/). |
| 23 | |
| 24 | Which checks a merge needs is up to the repository: its |
| 25 | [required status checks](#required-status-checks). The merge box lists |
| 26 | those first: |
| 27 | |
| 28 | ```text |
| 29 | Required checks: 1 of 2 passing |
| 30 | CI failing Details |
| 31 | Lint passing Details |
| 32 | ``` |
| 33 | |
| 34 | Each required check is **passing**, **failing**, **running**, or |
| 35 | **expected**, "waiting for status to be reported", when nothing has |
| 36 | reported it on the head commit yet. **Details** opens the run that |
| 37 | reported it. Below them are all the other checks, workflow runs job by job, |
| 38 | each with its state and how long it took. A check that is not required is |
| 39 | shown, but never holds a merge. |
| 40 | |
| 41 | A workflow job's **Details** opens its log on the run's page, where every |
| 42 | step's output is kept. |
| 43 | |
| 44 | A closed or merged pull request keeps a checks section in its conversation: |
| 45 | its head commit's workflow runs, job by job, as they ended, each with |
| 46 | **Details** to its log. It is there to read; nothing in it can be re-run, |
| 47 | and it says nothing about merging. |
| 48 | |
| 49 | ### Other attempts at the same work item |
| 50 | |
| 51 | When a work item has more than one pull request in a repository, for |
| 52 | example because two people or two coding agents each tried it, every one |
| 53 | of them shows **Other attempts at #N**: the pull requests for that work |
| 54 | item in the repository side by side, this one first. Each row has its |
| 55 | state (open, merged, or closed because another was merged instead), its |
| 56 | head commit's checks, where its review stands, its size, and the files it |
| 57 | changes that this one changes too. Pull requests for the same work item are |
| 58 | alternatives, so they are not listed under **Other work is changing the |
| 59 | same files**; that box is for work on other work items, which will |
| 60 | collide. |
| 61 | |
| 62 | ### Running them again |
| 63 | |
| 64 | People with the Write [role](/guides/access-and-roles/) or higher can press |
| 65 | **Re-run failed jobs** on a workflow run that failed, to run its failed jobs |
| 66 | again on the same commit. Every push to the pull request runs its workflows |
| 67 | again on the new head. |
| 68 | |
| 69 | g1t's own **Dependency review** check has **Re-run dependency review** |
| 70 | beside it, for the same people, since advisories are published every day: |
| 71 | it reviews the head again and updates the check and its one comment. See |
| 72 | [dependency review](/guides/security/supply-chain/#dependency-review). |
| 73 | |
| 74 | ### A repository with no checks |
| 75 | |
| 76 | When a repository has no workflows, the merge box says **This repository |
| 77 | has no checks**: nothing proves a change works. |
| 78 | **Add CI** writes a starter workflow for you; see |
| 79 | [add CI](/guides/actions/#add-ci). The same offer is on the |
| 80 | **Branches and merging** settings page and the **Actions** page. |
| 81 | |
| 82 | ## Required status checks |
| 83 | |
| 84 | What a pull request needs before it merges is set by the |
| 85 | [rulesets](/guides/rules/) that cover the branch it merges into, the |
| 86 | repository's and its workspace's. They hold for every pull request into |
| 87 | that branch, whoever opened it. Someone with the Admin |
| 88 | [role](/guides/access-and-roles/) sets them under the |
| 89 | repository's **Settings → Rules**: |
| 90 | |
| 91 | | Rule | What it does | |
| 92 | | --- | --- | |
| 93 | | Require a pull request before merging | Refuses pushes to the branch, so changes reach it only by merging. Sets the approvals a merge needs, whether approvals before the latest push count, and whether [code owners](/guides/codeowners/#require-review-from-code-owners) must approve. | |
| 94 | | Require status checks to pass | The checks that must pass on a pull request's head before it merges, whether it must be up to date with the branch first, whether someone who may merge can bypass the checks, and optionally only when some paths change. | |
| 95 | | Require the merge queue | See [merge queue](/guides/merge-queue/). | |
| 96 | | Require deployments to succeed | A pull request's head must have deployed to these environments. | |
| 97 | |
| 98 | [Rules](/guides/rules/#rules) lists every rule, including those for |
| 99 | sensitive paths and merge windows. |
| 100 | The merge box on a pull request lists each rule it does not meet yet, with |
| 101 | the ruleset it comes from and what to do about it. |
| 102 | |
| 103 | ### Choosing the checks |
| 104 | |
| 105 | **Require status checks to pass** offers the check names reported on the |
| 106 | repository's commits in the last 30 days. Pick from them, or type a name |
| 107 | that has not reported yet. A check can be pinned to the integration that |
| 108 | must report it, such as workflows or deployments. |
| 109 | |
| 110 | A required check is met by a status of that name on the pull request's head, |
| 111 | whatever event reported it, or by a [g1t Actions](/guides/actions/) job |
| 112 | of that name, as on GitHub. A job's check is named as GitHub names it: |
| 113 | the job's `name:` (or its id), with a matrix combination's values after it |
| 114 | in brackets, such as `test` or `build (ubuntu-latest, 22)`, and |
| 115 | `<calling job> / <job>` for a job of a called workflow. A branch rule |
| 116 | copied from GitHub that requires `test` is met by the `test` job, and one |
| 117 | that requires the workflow's name, such as `CI`, is met by the whole run. |
| 118 | Type a job's name to require it: the list offers the names of statuses. |
| 119 | Each job's latest attempt counts. One that was skipped passes the check, |
| 120 | and one that was cancelled fails it. |
| 121 | |
| 122 | | What reported it | What the merge does | |
| 123 | | --- | --- | |
| 124 | | A status that failed | Refused: "The required check CI failed." | |
| 125 | | A status still pending | Held: "The required check CI has not finished." | |
| 126 | | Nothing yet | Held: "The required check CI has not reported on its latest commit." | |
| 127 | | Success | Allowed | |
| 128 | |
| 129 | The same rule holds wherever a pull request merges: the merge button, |
| 130 | [`merge_pull_request`](/reference/api/pull-requests/merge-pull-request/), |
| 131 | auto-merge and the [merge queue](/guides/merge-queue/). Where the rule lets a merger bypass the |
| 132 | required checks, the merge button has a **bypass** box, and the API takes |
| 133 | `ignore_checks: true`. |
| 134 | |
| 135 | A check that only exists once a workflow has run, such as `CI` from a |
| 136 | workflow added in a pull request, appears in the list after that workflow |
| 137 | has run once. |
| 138 | |
| 139 | ### From the API |
| 140 | |
| 141 | ```sh |
| 142 | curl https://api.g1t.sh/repos/<workspace>/<repo>/check-names \ |
| 143 | -H "Authorization: Bearer $G1T_TOKEN" |
| 144 | ``` |
| 145 | |
| 146 | [`list_check_names`](/reference/api/repositories/list-check-names/) |
| 147 | returns the names seen in the last 30 days, most recent first, each as |
| 148 | `{name, events, last_seen}`. It needs the `repo:read` scope. |
| 149 | |
| 150 | ```sh |
| 151 | curl -X PATCH https://api.g1t.sh/repos/<workspace>/<repo>/settings \ |
| 152 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 153 | -H "Content-Type: application/json" \ |
| 154 | -d '{"required_checks": ["CI", "g1t / deploy"]}' |
| 155 | ``` |
| 156 | |
| 157 | [`update_repo_settings`](/reference/api/repositories/update-repo-settings/) |
| 158 | takes `required_checks`, which replaces the whole list, along with |
| 159 | `required_approvals`, `require_up_to_date`, |
| 160 | `merge_queue`, `allow_ignoring_checks` and `require_code_owner_review`, and |
| 161 | the repository's [merge settings](/guides/managing-repositories/#pull-requests); |
| 162 | [`get_repo_settings`](/reference/api/repositories/get-repo-settings/) |
| 163 | returns them. On the MCP server they are the `repository` tool's |
| 164 | `check_names`, `get_settings` and `update_settings` actions. They read and |
| 165 | write the "Default branch protection" ruleset; [rulesets](/guides/rules/#from-the-api) |
| 166 | have routes of their own. |
| 167 | |
| 168 | ## Reviewers |
| 169 | |
| 170 | Ask people to review a pull request in the **Reviewers** box on its page, |
| 171 | by username. You can also ask a [team](/guides/teams/), as |
| 172 | `@workspace/team`: everyone in it is asked, or, with the team's |
| 173 | [review assignment](/guides/teams/#review-assignment) on, g1t picks who, |
| 174 | and they are listed beside the team. Asking needs the Triage |
| 175 | [role](/guides/access-and-roles/) or higher, or being the pull request's |
| 176 | author. Nobody is asked to review their own pull request. |
| 177 | |
| 178 | When the repository has a [CODEOWNERS file](/guides/codeowners/), the |
| 179 | owners of the files a pull request changes are asked by themselves, and |
| 180 | the pull request shows **Code owners**: who owns which files and whose |
| 181 | approval is still needed. Where the rules do not require code owners' |
| 182 | approval, the box says **Approval not required**, and a rule nobody has |
| 183 | approved yet says **No approval yet**: nothing is waiting on it. |
| 184 | |
| 185 | Through the API, `POST /repos/{owner}/{name}/pulls/{number}/requested_reviewers` |
| 186 | takes `reviewers` (usernames) and `team_reviewers` (teams, as |
| 187 | `workspace/team` or the team's slug), and adds them to whoever is asked |
| 188 | already; `DELETE` on the same route takes requests away. On |
| 189 | the MCP server they are the `pull_request` tool's `request_reviewers` and |
| 190 | `remove_requested_reviewers` actions. |
| 191 | |
| 192 | ### Reviewing |
| 193 | |
| 194 | Anyone signed in other than its author can review an open pull request. |
| 195 | Write in the comment box under the conversation, then choose **Comment**, |
| 196 | **Approve** or **Request changes**. |
| 197 | |
| 198 | A review that only approves or requests changes, with nothing written and |
| 199 | no line it is about, shows as one line in the conversation, the way an |
| 200 | event does: who reviewed, **approved these changes** or **requested |
| 201 | changes**, and when. A coding agent's review shows its name with its |
| 202 | **Agent** badge and an **Advisory** chip: an agent's review never counts |
| 203 | toward required approvals or code owners. A review with text, or one on a |
| 204 | line of a file, keeps a card of its own, like a comment. |
| 205 | |
| 206 | ## Sessions |
| 207 | |
| 208 | Each session that works on a pull request, or on its work item, shows in the |
| 209 | conversation as a card where it started, the way a comment or a review |
| 210 | does: who it is (or g1t, working for someone), where it stands, its |
| 211 | branch, and its report once it ends, linked to its page. Mention `@g1t` |
| 212 | in a comment to have g1t carry on with the pull request; see |
| 213 | [assign g1t, or ask it in the thread](/guides/sessions/#assign-g1t-or-ask-it-in-the-thread). |
| 214 | |
| 215 | A coding agent that works on a pull request can record how it made the |
| 216 | change, entry by entry, with the `pull_request` tool's `record_session` |
| 217 | action. Read it on the pull request's **Session** tab, or with |
| 218 | `read_session`. Blame uses it to say why a line is the way it is. See |
| 219 | [sessions and why-blame](/guides/why-blame/). |
| 220 | |
| 221 | ## Files changed |
| 222 | |
| 223 | The **Files changed** tab lists every file the pull request changes, with |
| 224 | a tree of them beside the diffs and how many lines each adds and removes. |
| 225 | A commit's page and a comparison of two branches show their changes the |
| 226 | same way. |
| 227 | |
| 228 | A large change opens quickly however many files it has. The page arrives |
| 229 | with the first files' lines, about 2,000 of them, and the rest of the list |
| 230 | with their counts; each later file's lines load as you scroll near it. |
| 231 | Files with comments on their lines arrive with the page wherever they are, |
| 232 | so their comments are there at once. |
| 233 | |
| 234 | A file whose diff is longer than 1,000 lines (a lockfile or generated |
| 235 | code, usually) waits until you press **Load diff**. A link to a file |
| 236 | (`#file-` and its path, such as `…/pull/12/files#file-src/app.ts`) |
| 237 | opens it and loads its lines at once, however long. |
| 238 | |
| 239 | Some changes are too large to read in one go: |
| 240 | |
| 241 | - A comparison lists at most 300 files. When more changed, the page says |
| 242 | so under the last one. |
| 243 | - Lines are read for the first files until about 20,000 have been read. |
| 244 | The files after that are listed without their counts and load the same |
| 245 | way as you reach them; until then the toolbar says how many files are |
| 246 | not counted. |
| 247 | - A file over 512 KB, or a binary one, is listed without its contents. |
| 248 | |
| 249 | From the API, `get_pull_request_changes` works the same way: a file left |
| 250 | out has `omitted: true`, and asking again with its path in `paths` (up to |
| 251 | 50 at a time) returns its lines. |
| 252 | |
| 253 | ## Drafts, closing and reopening |
| 254 | |
| 255 | A draft is still being worked on: it can be reviewed, but it cannot merge |
| 256 | until it is marked ready for review. Its author and anyone with the Triage [role](/guides/access-and-roles/) or higher can |
| 257 | move a pull request between these states. An |
| 258 | [archived](/guides/managing-repositories/) repository refuses all of them. |
| 259 | |
| 260 | ### Open a draft |
| 261 | |
| 262 | When you open a pull request from a branch, choose **Open as draft** to |
| 263 | say it isn't ready yet. Push to the branch as often as you like; select |
| 264 | **Mark ready for review** when it is. Through the API, send `"draft": true` when you open it. |
| 265 | |
| 266 | ### Convert to a draft |
| 267 | |
| 268 | To take a pull request that is ready for review back to a draft, select |
| 269 | **Convert to draft** under the comment box. It leaves the |
| 270 | [merge queue](/guides/merge-queue/) if it is in it, and a merge that was |
| 271 | waiting for it to catch up is called off. Mark it ready again with |
| 272 | **Mark ready for review**. |
| 273 | |
| 274 | Only an open pull request can be converted; a draft, a closed or a merged |
| 275 | one is refused with `409`. |
| 276 | |
| 277 | ### Reopen a pull request |
| 278 | |
| 279 | To open a closed pull request again, select **Reopen pull request** under |
| 280 | the comment box. It comes back as it was when it was closed: a draft if it |
| 281 | was closed as a draft, otherwise ready for review. Its checks and whether |
| 282 | it merges cleanly are worked out again. |
| 283 | |
| 284 | A merged pull request cannot be reopened. Neither can one from a branch of |
| 285 | the repository whose branch was deleted: push the branch again first. |
| 286 | |
| 287 | ### From the API |
| 288 | |
| 289 | | To | Call | MCP | |
| 290 | | --- | --- | --- | |
| 291 | | Convert to a draft | `POST /repos/{owner}/{name}/pulls/{number}/draft` | `pull_request` with `"action": "draft"` | |
| 292 | | Close | `POST /repos/{owner}/{name}/pulls/{number}/close`, or `PATCH /repos/{owner}/{name}/pulls/{number}` with `"state": "closed"` | `pull_request` with `"action": "close"` | |
| 293 | | Reopen | `POST /repos/{owner}/{name}/pulls/{number}/reopen`, or `PATCH /repos/{owner}/{name}/pulls/{number}` with `"state": "open"` | `pull_request` with `"action": "reopen"` | |
| 294 | |
| 295 | Each answers with the pull request as it is now. Converting publishes |
| 296 | `pull.converted_to_draft` and reopening publishes `pull.reopened`, with the |
| 297 | head commit in `commit`; both reach [webhooks](/guides/webhooks/) and can |
| 298 | start [workflows](/guides/actions/). |
| 299 | |
| 300 | ## Editing and deleting comments |
| 301 | |
| 302 | You can edit and delete your own comments on work items and pull requests. |
| 303 | Anyone with the Maintain [role](/guides/access-and-roles/) or higher can |
| 304 | edit and delete anyone's. |
| 305 | |
| 306 | - To edit a comment, select **Edit** under it, change the text and select |
| 307 | **Save**. The comment shows **edited** beside its time. |
| 308 | - To delete a comment, select **Delete** under it and confirm. It is |
| 309 | removed for everyone and cannot be brought back. |
| 310 | |
| 311 | A review that approved or requested changes can be edited but not deleted, |
| 312 | so its verdict stays on record. One with nothing written has nothing to |
| 313 | edit, so it has neither. The notes in the timeline of what happened, |
| 314 | such as "closed this", cannot be edited or deleted. |
| 315 | |
| 316 | Through the API, `PATCH /workspaces/{workspace}/work/comments/{comment_id}` |
| 317 | with `body` edits a work item's comment and answers with it, and |
| 318 | `DELETE /workspaces/{workspace}/work/comments/{comment_id}` deletes it and |
| 319 | answers `204`; `PATCH` and `DELETE` |
| 320 | `/repos/{owner}/{name}/pulls/comments/{comment_id}` do the same for a pull |
| 321 | request's. Each comment's `id` is in |
| 322 | `GET /workspaces/{workspace}/work/{number}` and |
| 323 | `GET /repos/{owner}/{name}/pulls/{number}`. On the MCP server they are the |
| 324 | `work_item` and `pull_request` tools' `edit_comment` and `delete_comment` |
| 325 | actions. Editing |
| 326 | publishes `comment.edited`, with what the comment said before in |
| 327 | `changes.body.from`; deleting publishes `comment.deleted`, with the comment |
| 328 | as it was in `comment`. |
| 329 | |
| 330 | ## Reactions |
| 331 | |
| 332 | React to a work item's or pull request's description, or to any comment on |
| 333 | it, with one of eight emoji: 👍 👎 😄 🎉 😕 ❤️ 🚀 👀. Select the smiley |
| 334 | under it, or a reaction already there to add or take back yours; hovering |
| 335 | one says who reacted. Anyone who can read it may react. g1t |
| 336 | reacts 👀 to what it was asked to take on. |
| 337 | |
| 338 | Through the API, `POST /workspaces/{workspace}/work/{number}/reactions` |
| 339 | (or `POST /repos/{owner}/{name}/pulls/{number}/reactions`) with `content` (`+1`, `-1`, `laugh`, `hooray`, `confused`, `heart`, |
| 340 | `rocket` or `eyes`), and `comment_id` to react to a comment rather than |
| 341 | the description, reacts and answers with the reactions it has now; |
| 342 | `remove: true` takes yours back. On the MCP server it is the `work_item` |
| 343 | and `pull_request` tools' `react` action. Each comment's `reactions`, and |
| 344 | the description's, are in `GET /workspaces/{workspace}/work/{number}` and |
| 345 | `GET /repos/{owner}/{name}/pulls/{number}`: each with its `content`, |
| 346 | `count` and the `users` who reacted. |
| 347 | |
| 348 | ## Images |
| 349 | |
| 350 | To show an image in a pull request's or a work item's description, or in a |
| 351 | comment (a screenshot of a preview, say), upload it and paste the Markdown |
| 352 | you get back. From a shell, `g1t attach preview.png` prints |
| 353 | ``, and `--attach |
| 354 | preview.png` on `g1t pr create`, `g1t pr ready`, `g1t pr comment`, |
| 355 | `g1t work new` and `g1t work comment` adds it for you (see the |
| 356 | [CLI guide](/guides/cli/#images-in-descriptions-and-comments)). Through the API it is |
| 357 | [`POST /repos/{owner}/{name}/attachments`](/reference/api/work-items/upload-attachment/) |
| 358 | with `name`, the file base64-encoded in `data`, and optionally |
| 359 | `content_type`; it answers with `id`, `url`, `content_type`, `size` and |
| 360 | `markdown`. A work item keeps its own: |
| 361 | [`POST /workspaces/{workspace}/work/{number}/attachments`](/reference/api/work-items/upload-work-item-attachment/) |
| 362 | takes the same and answers the same, so a work item filed with no |
| 363 | repository takes images too; anyone who may comment on the work item may. |
| 364 | On the MCP server they are the `pull_request` tool's `attach` action and |
| 365 | the `work_item` tool's. |
| 366 | |
| 367 | An attachment is a PNG, JPEG, GIF or WebP image of at most 10 MB, judged by |
| 368 | its bytes: a larger file is refused with `413` (`too_large`), anything else |
| 369 | with `415` (`unsupported_type`). Anyone who may comment on the repository |
| 370 | may upload one, with `work:write`. It is served from g1t's usercontent |
| 371 | address, never g1t.sh, and its address is its permission: anyone given the |
| 372 | link can see the image, even one from a private repository. A purged |
| 373 | repository's attachments are deleted with it. |
| 374 | |
| 375 | ## Commit comments |
| 376 | |
| 377 | You can comment on any commit: on the whole commit, under its changes on |
| 378 | the commit's page, or on one line of a file it changed, from the **+** |
| 379 | beside the line. A comment on a line stays with that line of the file as |
| 380 | the commit left it. Anyone who can read the repository can read and write |
| 381 | them, unless the repository has turned commit comments off in its |
| 382 | [settings](/guides/managing-repositories/#commits), which keeps the |
| 383 | comments already made readable. |
| 384 | The commit's author and anyone mentioned are notified. |
| 385 | |
| 386 | You can edit and delete your own commit comments; anyone with the Maintain |
| 387 | [role](/guides/access-and-roles/) or higher can delete anyone's. |
| 388 | |
| 389 | | To | API | MCP (`repository`) | |
| 390 | | --- | --- | --- | |
| 391 | | List a repository's, newest first | `GET /repos/{owner}/{name}/comments` (`page`, 30 a page) | `list_commit_comments` | |
| 392 | | List a commit's, oldest first | `GET /repos/{owner}/{name}/commits/{sha}/comments` | `commit_comments` | |
| 393 | | Comment | `POST /repos/{owner}/{name}/commits/{sha}/comments` with `body`, and `path` and `line` for a line | `comment_on_commit` | |
| 394 | | Edit | `PATCH /repos/{owner}/{name}/comments/{comment_id}` with `body` | `edit_commit_comment` | |
| 395 | | Delete | `DELETE /repos/{owner}/{name}/comments/{comment_id}`, which answers `204` | `delete_commit_comment` | |
| 396 | |
| 397 | Reading needs the `repo:read` scope; commenting, editing and deleting need |
| 398 | `work:write`, as comments on work items do. Each publishes |
| 399 | `commit_comment.created`, `commit_comment.edited` or |
| 400 | `commit_comment.deleted` to [webhooks](/guides/webhooks/). |
| 401 | |
| 402 | ## Merging a pull request |
| 403 | |
| 404 | A pull request merges once it is ready for review, merges cleanly and meets |
| 405 | every rule for the branch it merges into. Merging needs the Write |
| 406 | [role](/guides/access-and-roles/) or higher. Choose how it merges from the |
| 407 | merge button's menu; the button offers the repository's default method |
| 408 | first. |
| 409 | |
| 410 | ### Merge methods |
| 411 | |
| 412 | | Method | Name in the API | What lands on the base | |
| 413 | | --- | --- | --- | |
| 414 | | Create a merge commit | `merge` | Every commit of the branch, and a merge commit on top whose parents are the base and the branch. | |
| 415 | | Squash and merge | `squash` | One new commit holding everything the pull request changed, authored by whoever the pull request is for (its author, or whoever asked g1t for it), with you as committer and a `Co-authored-by:` trailer for every other author of its commits. | |
| 416 | | Rebase and merge | `rebase` | Each commit of the branch, made again on top of the base in order, keeping its author, date and message, with you as committer and a new hash. Merge commits and commits the base already has are left out. The base moves to the last of them. | |
| 417 | | Fast-forward | `fast_forward` | Nothing new: the base moves to the branch's head, the exact commit its checks ran on. Only possible when the branch contains the base's head; [update the branch](#keeping-it-up-to-date) first otherwise. | |
| 418 | |
| 419 | A repository chooses the methods it allows, and which one is offered first, |
| 420 | in its [settings](/guides/managing-repositories/#pull-requests). A |
| 421 | [rule](/guides/rules/#pull-requests-and-checks) for the base branch can narrow them |
| 422 | further: `allowed_merge_methods` lists the methods a merge into that branch |
| 423 | may use, and **Require linear history** refuses `merge`, the one method |
| 424 | that lands a commit with two parents. The merge button offers only the |
| 425 | methods both allow, and a merge by any other method is refused, from the |
| 426 | API and the CLI too. |
| 427 | |
| 428 | Merging is line-level: edits to the same file merge when their lines do |
| 429 | not clash. A merge that would clash is refused with nothing changed and |
| 430 | names the files; a `rebase` stops at the first commit that conflicts and |
| 431 | names it too. Resolve the [conflicts](#conflicts) and push, or choose |
| 432 | another method. |
| 433 | |
| 434 | g1t merges, squashes and rebases by itself up to 1,000 changed files, 100 |
| 435 | files merged line by line (1 MiB each) and 250 commits in a rebase. Beyond |
| 436 | those it refuses and nothing changes: squash or merge instead of rebasing, |
| 437 | or merge the base in a clone. |
| 438 | |
| 439 | With the [merge queue](/guides/merge-queue/#how-entries-are-tested) on, |
| 440 | the method chosen (or the queue rule's, when none is) decides how the |
| 441 | pull request's state is built in the queue, and what is tested is what |
| 442 | lands. |
| 443 | |
| 444 | ### Commit messages |
| 445 | |
| 446 | A merge commit and a squash commit get a message. You can write it in the |
| 447 | merge box before you confirm, or with `commit_title` and `commit_message` |
| 448 | in the API. Otherwise the repository's default decides: |
| 449 | |
| 450 | | Default | Merge commit | Squash commit | |
| 451 | | --- | --- | --- | |
| 452 | | `default` | **Merge pull request #12 from *owner/branch***, with its title below | Its title with its number, **Greet the caller (#12)**; with more than one commit, a list of their subjects below | |
| 453 | | `pull_title` | Its title, with its number: **Greet the caller (#12)** | The same | |
| 454 | | `pull_title_and_description` | Its title, with its number, and its description below | The same | |
| 455 | | `pull_title_and_commits` | Not offered | Its title, with its number, and each commit's message below | |
| 456 | | `custom` | The repository's merge commit template | The repository's squash commit template | |
| 457 | |
| 458 | A template is the whole message, its first line the title. These |
| 459 | placeholders are filled in: |
| 460 | |
| 461 | | Placeholder | Becomes | |
| 462 | | --- | --- | |
| 463 | | `{title}` | The pull request's title | |
| 464 | | `{number}` | Its number, without `#` | |
| 465 | | `{body}` | Its description | |
| 466 | | `{branch}` | The branch it merges from | |
| 467 | | `{head_repo}` | The repository that branch is in, as `owner/name` | |
| 468 | | `{base}` | The branch it merges into | |
| 469 | | `{author}` | Its author's username | |
| 470 | | `{commits}` | Its commits' subjects, one `* subject` line each | |
| 471 | | `{items}` | The work items it lands on, as `#12, #14` | |
| 472 | | `{co_authors}` | A `Co-authored-by:` line for each author of its commits, each once | |
| 473 | |
| 474 | ```text |
| 475 | {title} (#{number}) |
| 476 | |
| 477 | {body} |
| 478 | |
| 479 | Closes {items} |
| 480 | {co_authors} |
| 481 | ``` |
| 482 | |
| 483 | Each placeholder is filled in once, and what it holds is never read as |
| 484 | another placeholder. A name not in the table stays as written. |
| 485 | |
| 486 | Where the repository requires sign-off on web commits, every commit g1t |
| 487 | makes when merging (the merge or squash commit, and each rebased commit) |
| 488 | ends with a `Signed-off-by:` trailer for whoever merged. |
| 489 | |
| 490 | ### Auto-merge |
| 491 | |
| 492 | Turn on auto-merge when a pull request is waiting only on its checks or |
| 493 | reviews: it merges by itself, as you, by the method you chose, as soon as |
| 494 | everything it needs is met. A pull request that may merge already merges at |
| 495 | once instead. The repository must allow auto-merge (on by default), and you |
| 496 | need the Write role, since it merges as you; its author can also turn it |
| 497 | off. |
| 498 | |
| 499 | Auto-merge stays on until the pull request merges or closes, until someone |
| 500 | turns it off, or until someone other than whoever turned it on pushes to it, |
| 501 | so a push nobody reviewed never lands by itself. Turning it on and off |
| 502 | publishes `pull.auto_merge_enabled` and `pull.auto_merge_disabled`. |
| 503 | |
| 504 | When auto-merge turns off without you, you get a notification saying |
| 505 | why, since it will not merge on its own now. Where the repository uses a |
| 506 | merge queue, a pull request auto-merge hands to the queue lands as the |
| 507 | queue decides; that turns auto-merge off too, but nothing is left for you |
| 508 | to do, so it tells no one. |
| 509 | |
| 510 | ### Merging by pushing |
| 511 | |
| 512 | A pull request also merges when its head commit reaches the branch it |
| 513 | merges into some other way: you merge the branch in a clone and push, or |
| 514 | push its commits straight to the base. When a push to a branch brings in |
| 515 | the head commit of an open pull request into that branch (a draft too), |
| 516 | the pull request is marked merged, by whoever pushed, with `merge_commit` |
| 517 | set to the commit the branch was pushed to. It is the same as any other |
| 518 | merge: it lands on the work items it closes, the other pull requests for |
| 519 | its work item in the repository close as superseded, it leaves the merge queue, and `pull.merged` is |
| 520 | published. Its timeline says **merged this by pushing** that commit **to** |
| 521 | the branch. |
| 522 | |
| 523 | Only the head commit counts: a push that brings in some of a pull |
| 524 | request's commits but not the last leaves it open. A head commit the branch |
| 525 | already held before the push (a branch opened at a commit of the base, with |
| 526 | nothing on it yet) does not merge it either. Its branch is not deleted. |
| 527 | |
| 528 | ### Closing work items |
| 529 | |
| 530 | When a pull request merges into the default branch, it lands its |
| 531 | repository on the work item it was made for, and on every work item its |
| 532 | title or description names after a closing keyword (`Closes #12`, |
| 533 | `Fixes #12`, `Resolves #12`, and their other forms). A work item closes |
| 534 | once every repository it targets has landed, or at the first landing when |
| 535 | it has no target. `Part of #12` (or `Refs #12`) links the pull request |
| 536 | without landing anything. Commits pushed to the default branch land work |
| 537 | items the same way. |
| 538 | |
| 539 | The pull request's `closes` lists the work items it will land on, in the |
| 540 | order named, and `parts` the ones it is part of. Merging into any other |
| 541 | branch lands nothing, and a repository can turn this off with |
| 542 | `auto_close_items`. [Closing work items](/work/closing/) has the whole of |
| 543 | it: the keywords, landing target by target, commits, closing by hand or |
| 544 | with a commit, and reopening. |
| 545 | |
| 546 | Wherever a commit's message shows, `#12` links to that work item or pull |
| 547 | request, with its title and state when you hover over it. Old issue |
| 548 | numbers written before work items still link to the work item each became. |
| 549 | |
| 550 | ### Deleting the branch |
| 551 | |
| 552 | After a pull request from a branch merges or closes, the merge box offers |
| 553 | **Delete branch**. A repository can have it done on every merge |
| 554 | (`delete_branch_on_merge`), and a merge can ask for it or against it |
| 555 | (`delete_branch`). **Restore branch** makes it again at the pull request's |
| 556 | head commit, as long as no branch of that name exists. Both need the Write |
| 557 | role, or push access to the fork for a fork's branch, and publish |
| 558 | `pull.head_branch_deleted` and `pull.head_branch_restored`. |
| 559 | |
| 560 | The default branch, a branch another open pull request merges from, and a |
| 561 | branch a rule protects from deletion are never deleted. |
| 562 | |
| 563 | ### From the API and the CLI |
| 564 | |
| 565 | | To | API | MCP (`pull_request`) | CLI | |
| 566 | | --- | --- | --- | --- | |
| 567 | | Merge | `POST /repos/{owner}/{name}/pulls/{number}/merge` with `merge_method`, `commit_title`, `commit_message`, `sha`, `delete_branch` | `merge` | `g1t pr merge 12 --squash` | |
| 568 | | Turn on auto-merge | `PUT /repos/{owner}/{name}/pulls/{number}/auto-merge` with `merge_method`, `commit_title`, `commit_message` | `enable_auto_merge` | `g1t pr merge 12 --auto --squash` | |
| 569 | | Turn off auto-merge | `DELETE /repos/{owner}/{name}/pulls/{number}/auto-merge` | `disable_auto_merge` | `g1t pr merge 12 --disable-auto` | |
| 570 | | Update its branch | `PUT /repos/{owner}/{name}/pulls/{number}/update-branch` with `update_method`, `expected_head_sha` | `update_branch` | `g1t pr update-branch 12 --rebase` | |
| 571 | | Delete its branch | `DELETE /repos/{owner}/{name}/pulls/{number}/head-branch` | `delete_branch` | `g1t pr merge 12 --delete-branch`, as it merges | |
| 572 | | Restore its branch | `POST /repos/{owner}/{name}/pulls/{number}/head-branch/restore` | `restore_branch` | | |
| 573 | | See how it may merge | `GET /repos/{owner}/{name}/pulls/{number}/merge-options` | `merge_options` | | |
| 574 | |
| 575 | Give `sha` (`--match-head-commit` in the CLI) with the head commit you |
| 576 | reviewed, and the merge is refused with `409` if anything was pushed since. |
| 577 | A merged pull request has `merge_method` and `merge_commit`: the merge or |
| 578 | squash commit, the last rebased commit, or its head for a fast-forward. |
| 579 | `auto_merge` holds the method, message, who turned it on and when. |
| 580 | |
| 581 | `merge-options` answers what the merge box shows you: the `methods` it may |
| 582 | merge by and the `default_method`, each method's default commit message in |
| 583 | `options` (with `unavailable` saying why one cannot be used now), whether |
| 584 | it is `behind`, `can_fast_forward`, should be offered an update |
| 585 | (`suggest_update`), goes through the `merge_queue`, whether you may turn on |
| 586 | auto-merge (`auto_merge_allowed`), whether deleting its branch starts |
| 587 | ticked (`delete_branch_default`, `can_delete_branch`), and whether commits |
| 588 | made merging it are signed off (`sign_off`). |
| 589 | |
| 590 | ## Conflicts |
| 591 | |
| 592 | g1t works out whether a pull request merges cleanly into its target before |
| 593 | anyone tries to merge it, and again whenever either side moves: a push to |
| 594 | the pull request, or anything landing on the target branch. |
| 595 | |
| 596 | 1. **Without a sandbox.** g1t compares the files the pull request changed |
| 597 | since it and the target last agreed with the files the target changed |
| 598 | since then. If they share none, the merge cannot conflict, and that is |
| 599 | the answer. |
| 600 | 2. **With a short probe.** If they share files, a sandbox merges the two |
| 601 | commits and pushes nothing, and reports the files that |
| 602 | conflict. Meanwhile the box says **Checking whether this merges cleanly**, |
| 603 | and the merge button waits. Probes are charged as runner minutes; each |
| 604 | pair of commits is probed once, and a repository runs at most |
| 605 | three at a time, the rest following in turn. |
| 606 | |
| 607 | A pull request that conflicts shows **This branch has conflicts that must |
| 608 | be resolved**, the conflicting files, each linked to its diff, and how to |
| 609 | resolve them: |
| 610 | |
| 611 | - **Resolve in the browser.** Coming soon. |
| 612 | - **On the command line.** The box lists the commands, each with a copy |
| 613 | button. For a pull request from a branch: |
| 614 | |
| 615 | ```sh |
| 616 | git fetch origin |
| 617 | git checkout my-branch |
| 618 | git merge origin/main |
| 619 | # fix each conflicting file, then |
| 620 | git add -A && git commit --no-edit |
| 621 | git push origin my-branch |
| 622 | ``` |
| 623 | |
| 624 | For a pull request in its own [working copy](/concepts/forks/#working-copies-for-pull-requests), clone the working copy and pull `main` into |
| 625 | it instead: |
| 626 | |
| 627 | ```sh |
| 628 | git clone https://g1t.sh/pulls/<id>.git && cd <id> |
| 629 | git pull --no-rebase https://g1t.sh/<owner>/<repo>.git main |
| 630 | ``` |
| 631 | |
| 632 | While it conflicts, it cannot be merged or added to the |
| 633 | [merge queue](/guides/merge-queue/), and the merge button says so. Once the |
| 634 | fix is pushed, g1t works it out again. |
| 635 | |
| 636 | A pull request that only has fallen behind its target, without conflicts, |
| 637 | still merges: merging brings it up to date first, unless the repository |
| 638 | requires pull requests to be up to date. Bringing it up to date makes a new |
| 639 | commit, so when the target branch requires checks, the merge box says |
| 640 | **Merging once checks pass** and the pull request lands when the required |
| 641 | checks pass on that commit, with nothing more to press. If one of them fails |
| 642 | there, it is not merged: the pull request says which check failed, and you |
| 643 | push a fix and merge again. With no required checks, it lands as soon as it |
| 644 | is up to date. |
| 645 | |
| 646 | If the repository does not answer in time while merging, the merge box says |
| 647 | g1t couldn't reach the repository. Merge again: if the first merge went |
| 648 | through meanwhile, merging again records it rather than merging twice. |
| 649 | |
| 650 | ## Keeping it up to date |
| 651 | |
| 652 | When the branch it merges into has moved, the merge box says **main has |
| 653 | moved since this was made**, and offers to update the branch. A repository |
| 654 | that requires pull requests to be up to date shows it whenever the branch |
| 655 | is behind; otherwise it shows it when the repository suggests updating |
| 656 | branches (on by default), and merging brings the branch up to date by |
| 657 | itself. Whoever can push to the pull request (whoever opened it, for one |
| 658 | in its own working copy; anyone with the Write [role](/guides/access-and-roles/) |
| 659 | or higher, for a branch of the repository; whoever can push to the fork, |
| 660 | for a branch of a fork) can update it, two ways: |
| 661 | |
| 662 | - **Merge.** g1t merges `main` into the branch. The merge commit is named |
| 663 | **Merge main into *branch***, has the pull request's head and `main`'s |
| 664 | head as its parents, and is authored and pushed as you. |
| 665 | - **Rebase.** g1t makes each of the branch's commits again on top of |
| 666 | `main`'s head and moves the branch there. Its history is rewritten, so |
| 667 | anyone with the branch checked out must reset to it before pushing |
| 668 | again. |
| 669 | |
| 670 | Either is done in a few seconds when the two sides' changes do not clash: |
| 671 | edits to different lines of the same file merge line by line. The |
| 672 | workflows then run again on the new head, as after any push. The update is |
| 673 | pushed only if the branch is still where it was when it started: if |
| 674 | someone pushed meanwhile, it stops with nothing lost, and you can try again. |
| 675 | When both changed the same lines, or one deleted a file the other changed, |
| 676 | nothing is pushed and the files are named: merge or rebase `main` in |
| 677 | yourself, with the commands under [conflicts](#conflicts). A rebase stops |
| 678 | at the first commit that conflicts and names it. |
| 679 | |
| 680 | From the API, `PUT /repos/{owner}/{name}/pulls/{number}/update-branch` takes |
| 681 | `update_method` (`merge`, the default, or `rebase`) and `expected_head_sha`, |
| 682 | and answers with `outcome`: `updated`, `up_to_date`, or `needs_agent` when |
| 683 | nothing was pushed. On the MCP server it is the `pull_request` tool's |
| 684 | `update_branch` action; in the CLI, `g1t pr update-branch 12 --rebase`. |
| 685 | |
| 686 | ## From the API |
| 687 | |
| 688 | `GET /repos/{owner}/{name}/pulls/{number}` returns, besides the pull request: |
| 689 | |
| 690 | | Field | What it is | |
| 691 | | --- | --- | |
| 692 | | `statuses` | What each workflow run, and anything else that reports statuses, said about its head, with a link to the run. | |
| 693 | | `required_checks` | Each check the default branch requires, as it stands on the head: `name`, `state` (`success`, `failure`, `pending`, or `expected` when nothing has reported it yet), `description` and `target_url`. Empty when none are required. | |
| 694 | | `checks` | The latest record against its head from g1t itself, such as the merge queue taking it out, with `earlier_checks` before it. | |
| 695 | | `mergeable` | `clean`, `conflicting`, `checking` or `unknown`. | |
| 696 | | `conflicts` | When conflicting, the files that conflict. | |
| 697 | | `behind` | Whether its target has moved on without it. | |
| 698 | | `merge_method`, `merge_commit` | Once merged: how, and the commit its base was left at. | |
| 699 | | `auto_merge` | When auto-merge is on: `method`, `commit_title`, `commit_message`, `enabled_by` and `enabled_at`. | |
| 700 | | `item` | The number of the work item it was made for. | |
| 701 | | `closes`, `parts` | The work items it lands on when it merges into the default branch, and the ones it is part of. | |
| 702 | | `head_branch_deleted` | Whether its branch was deleted after it merged or closed. | |
| 703 | | `reviewers`, `team_reviewers` | The people and the [teams](/guides/teams/#review-requests) asked to review it. | |
| 704 | | `code_owners` | Who owns the files it changes and whose approval is still needed; see [CODEOWNERS](/guides/codeowners/#through-the-api). Absent when its target has no CODEOWNERS file. | |
| 705 | |
| 706 | A coding agent sees the same through the `pull_request` tool's `get` |
| 707 | action. |