| 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, drafts, closing and reopening, editing and deleting comments, and conflicts found before anyone tries to merge. |
| 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 issue |
| 50 | |
| 51 | When an issue has more than one pull request, for example because two |
| 52 | people or two coding agents each tried it, every one of them shows **Other attempts at #N**: the |
| 53 | pull requests for that issue side by side, this one first. Each row has its |
| 54 | state (open, merged, or closed because another was merged instead), its |
| 55 | head commit's checks, where its review stands, its size, and the files it |
| 56 | changes that this one changes too. Pull requests for the same issue are |
| 57 | alternatives, so they are not listed under **Other work is changing the |
| 58 | same files**; that box is for work on other issues, which will collide. |
| 59 | |
| 60 | ### Running them again |
| 61 | |
| 62 | People with the Write [role](/guides/access-and-roles/) or higher can press |
| 63 | **Re-run failed jobs** on a workflow run that failed, to run its failed jobs |
| 64 | again on the same commit. Every push to the pull request runs its workflows |
| 65 | again on the new head. |
| 66 | |
| 67 | ### A repository with no checks |
| 68 | |
| 69 | When a repository has no workflows, the merge box says **This repository |
| 70 | has no checks**: nothing proves a change works. |
| 71 | **Add CI** writes a starter workflow for you; see |
| 72 | [add CI](/guides/actions/#add-ci). The same offer is on the |
| 73 | **Branches and merging** settings page and the **Actions** page. |
| 74 | |
| 75 | ## Required status checks |
| 76 | |
| 77 | What a pull request needs before it merges is set by the |
| 78 | [rulesets](/guides/rules/) that cover the branch it merges into, the |
| 79 | repository's and its workspace's. They hold for every pull request into |
| 80 | that branch, whoever opened it. Someone with the Admin |
| 81 | [role](/guides/access-and-roles/) sets them under the |
| 82 | repository's **Settings → Rules**: |
| 83 | |
| 84 | | Rule | What it does | |
| 85 | | --- | --- | |
| 86 | | 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. | |
| 87 | | 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. | |
| 88 | | Require the merge queue | See [merge queue](/guides/merge-queue/). | |
| 89 | | Require deployments to succeed | A pull request's head must have deployed to these environments. | |
| 90 | |
| 91 | [Rules](/guides/rules/#rules) lists every rule, including those for |
| 92 | sensitive paths and merge windows. |
| 93 | The merge box on a pull request lists each rule it does not meet yet, with |
| 94 | the ruleset it comes from and what to do about it. |
| 95 | |
| 96 | ### Choosing the checks |
| 97 | |
| 98 | **Require status checks to pass** offers the check names reported on the |
| 99 | repository's commits in the last 30 days. Pick from them, or type a name |
| 100 | that has not reported yet. A check can be pinned to the integration that |
| 101 | must report it, such as workflows or deployments. |
| 102 | |
| 103 | A required check is met by a status of that name on the pull request's head, |
| 104 | whatever event reported it, or by a [g1t Actions](/guides/actions/) job |
| 105 | of that name, as on GitHub. A job's check is named as GitHub names it: |
| 106 | the job's `name:` (or its id), with a matrix combination's values after it |
| 107 | in brackets, such as `test` or `build (ubuntu-latest, 22)`, and |
| 108 | `<calling job> / <job>` for a job of a called workflow. A branch rule |
| 109 | copied from GitHub that requires `test` is met by the `test` job, and one |
| 110 | that requires the workflow's name, such as `CI`, is met by the whole run. |
| 111 | Type a job's name to require it: the list offers the names of statuses. |
| 112 | Each job's latest attempt counts. One that was skipped passes the check, |
| 113 | and one that was cancelled fails it. |
| 114 | |
| 115 | | What reported it | What the merge does | |
| 116 | | --- | --- | |
| 117 | | A status that failed | Refused: "The required check CI failed." | |
| 118 | | A status still pending | Held: "The required check CI has not finished." | |
| 119 | | Nothing yet | Held: "The required check CI has not reported on its latest commit." | |
| 120 | | Success | Allowed | |
| 121 | |
| 122 | The same rule holds wherever a pull request merges: the merge button, |
| 123 | [`merge_pull_request`](/reference/api/pull-requests/merge-pull-request/), |
| 124 | auto-merge and the [merge queue](/guides/merge-queue/). Where the rule lets a merger bypass the |
| 125 | required checks, the merge button has a **bypass** box, and the API takes |
| 126 | `ignore_checks: true`. |
| 127 | |
| 128 | A check that only exists once a workflow has run, such as `CI` from a |
| 129 | workflow added in a pull request, appears in the list after that workflow |
| 130 | has run once. |
| 131 | |
| 132 | ### From the API |
| 133 | |
| 134 | ```sh |
| 135 | curl https://api.g1t.sh/repos/<workspace>/<repo>/check-names \ |
| 136 | -H "Authorization: Bearer $G1T_TOKEN" |
| 137 | ``` |
| 138 | |
| 139 | [`list_check_names`](/reference/api/repositories/list-check-names/) |
| 140 | returns the names seen in the last 30 days, most recent first, each as |
| 141 | `{name, events, last_seen}`. It needs the `repo:read` scope. |
| 142 | |
| 143 | ```sh |
| 144 | curl -X PATCH https://api.g1t.sh/repos/<workspace>/<repo>/settings \ |
| 145 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 146 | -H "Content-Type: application/json" \ |
| 147 | -d '{"required_checks": ["CI", "g1t / deploy"]}' |
| 148 | ``` |
| 149 | |
| 150 | [`update_repo_settings`](/reference/api/repositories/update-repo-settings/) |
| 151 | takes `required_checks`, which replaces the whole list, along with |
| 152 | `required_approvals`, `require_up_to_date`, |
| 153 | `merge_queue`, `allow_ignoring_checks` and `require_code_owner_review`; |
| 154 | [`get_repo_settings`](/reference/api/repositories/get-repo-settings/) |
| 155 | returns them. On the MCP server they are the `repository` tool's |
| 156 | `check_names`, `get_settings` and `update_settings` actions. They read and |
| 157 | write the "Default branch protection" ruleset; [rulesets](/guides/rules/#from-the-api) |
| 158 | have routes of their own. |
| 159 | |
| 160 | ## Reviewers |
| 161 | |
| 162 | Ask people to review a pull request in the **Reviewers** box on its page, |
| 163 | by username. You can also ask a [team](/guides/teams/), as |
| 164 | `@workspace/team`: everyone in it is asked, or, with the team's |
| 165 | [review assignment](/guides/teams/#review-assignment) on, g1t picks who, |
| 166 | and they are listed beside the team. Asking needs the Triage |
| 167 | [role](/guides/access-and-roles/) or higher, or being the pull request's |
| 168 | author. Nobody is asked to review their own pull request. |
| 169 | |
| 170 | When the repository has a [CODEOWNERS file](/guides/codeowners/), the |
| 171 | owners of the files a pull request changes are asked by themselves, and |
| 172 | the pull request shows **Code owners**: who owns which files and whose |
| 173 | approval is still needed. |
| 174 | |
| 175 | Through the API, `POST /repos/{owner}/{name}/pulls/{number}/requested_reviewers` |
| 176 | takes `reviewers` (usernames) and `team_reviewers` (teams, as |
| 177 | `workspace/team` or the team's slug), and adds them to whoever is asked |
| 178 | already; `DELETE` on the same route takes requests away. On |
| 179 | the MCP server they are the `pull_request` tool's `request_reviewers` and |
| 180 | `remove_requested_reviewers` actions. |
| 181 | |
| 182 | ## Sessions |
| 183 | |
| 184 | A coding agent that works on a pull request can record how it made the |
| 185 | change, entry by entry, with the `pull_request` tool's `record_session` |
| 186 | action. Read it on the pull request's **Session** tab, or with |
| 187 | `read_session`. Blame uses it to say why a line is the way it is. See |
| 188 | [sessions and why-blame](/guides/why-blame/). |
| 189 | |
| 190 | ## Drafts, closing and reopening |
| 191 | |
| 192 | A draft is still being worked on: it can be reviewed, but it cannot merge |
| 193 | until it is marked ready for review. Its author and anyone with the Triage [role](/guides/access-and-roles/) or higher can |
| 194 | move a pull request between these states. An |
| 195 | [archived](/guides/managing-repositories/) repository refuses all of them. |
| 196 | |
| 197 | ### Open a draft |
| 198 | |
| 199 | When you open a pull request from a branch, choose **Open as draft** to |
| 200 | say it isn't ready yet. Push to the branch as often as you like; select |
| 201 | **Mark ready for review** when it is. Through the API, send `"draft": true` when you open it. |
| 202 | |
| 203 | ### Convert to a draft |
| 204 | |
| 205 | To take a pull request that is ready for review back to a draft, select |
| 206 | **Convert to draft** under the comment box. It leaves the |
| 207 | [merge queue](/guides/merge-queue/) if it is in it, and a merge that was |
| 208 | waiting for it to catch up is called off. Mark it ready again with |
| 209 | **Mark ready for review**. |
| 210 | |
| 211 | Only an open pull request can be converted; a draft, a closed or a merged |
| 212 | one is refused with `409`. |
| 213 | |
| 214 | ### Reopen a pull request |
| 215 | |
| 216 | To open a closed pull request again, select **Reopen pull request** under |
| 217 | the comment box. It comes back as it was when it was closed: a draft if it |
| 218 | was closed as a draft, otherwise ready for review. Its checks and whether |
| 219 | it merges cleanly are worked out again. |
| 220 | |
| 221 | A merged pull request cannot be reopened. Neither can one from a branch of |
| 222 | the repository whose branch was deleted: push the branch again first. |
| 223 | |
| 224 | ### From the API |
| 225 | |
| 226 | | To | Call | MCP | |
| 227 | | --- | --- | --- | |
| 228 | | Convert to a draft | `POST /repos/{owner}/{name}/pulls/{number}/draft` | `pull_request` with `"action": "draft"` | |
| 229 | | Close | `POST /repos/{owner}/{name}/pulls/{number}/close`, or `PATCH /repos/{owner}/{name}/pulls/{number}` with `"state": "closed"` | `pull_request` with `"action": "close"` | |
| 230 | | Reopen | `POST /repos/{owner}/{name}/pulls/{number}/reopen`, or `PATCH /repos/{owner}/{name}/pulls/{number}` with `"state": "open"` | `pull_request` with `"action": "reopen"` | |
| 231 | |
| 232 | Each answers with the pull request as it is now. Converting publishes |
| 233 | `pull.converted_to_draft` and reopening publishes `pull.reopened`, with the |
| 234 | head commit in `commit`; both reach [webhooks](/guides/webhooks/) and can |
| 235 | start [workflows](/guides/actions/). |
| 236 | |
| 237 | ## Editing and deleting comments |
| 238 | |
| 239 | You can edit and delete your own comments on issues and pull requests. |
| 240 | Anyone with the Maintain [role](/guides/access-and-roles/) or higher can |
| 241 | edit and delete anyone's. |
| 242 | |
| 243 | - To edit a comment, select **Edit** under it, change the text and select |
| 244 | **Save**. The comment shows **edited** beside its time. |
| 245 | - To delete a comment, select **Delete** under it and confirm. It is |
| 246 | removed for everyone and cannot be brought back. |
| 247 | |
| 248 | A review that approved or requested changes can be edited but not deleted, |
| 249 | so its verdict stays on record. The notes in the timeline of what happened, |
| 250 | such as "closed this", cannot be edited or deleted. |
| 251 | |
| 252 | Through the API, `PATCH /repos/{owner}/{name}/issues/comments/{comment_id}` |
| 253 | with `body` edits a comment and answers with it, and |
| 254 | `DELETE /repos/{owner}/{name}/issues/comments/{comment_id}` deletes it and |
| 255 | answers `204`. Both work for comments on issues and on pull requests; each |
| 256 | comment's `id` is in `GET /repos/{owner}/{name}/issues/{number}` and |
| 257 | `GET /repos/{owner}/{name}/pulls/{number}`. On the MCP server they are the |
| 258 | `issue` tool's `edit_comment` and `delete_comment` actions. Editing |
| 259 | publishes `comment.edited`, with what the comment said before in |
| 260 | `changes.body.from`; deleting publishes `comment.deleted`, with the comment |
| 261 | as it was in `comment`. |
| 262 | |
| 263 | ## Conflicts |
| 264 | |
| 265 | g1t works out whether a pull request merges cleanly into its target before |
| 266 | anyone tries to merge it, and again whenever either side moves: a push to |
| 267 | the pull request, or anything landing on the target branch. |
| 268 | |
| 269 | 1. **Without a sandbox.** g1t compares the files the pull request changed |
| 270 | since it and the target last agreed with the files the target changed |
| 271 | since then. If they share none, the merge cannot conflict, and that is |
| 272 | the answer. |
| 273 | 2. **With a short probe.** If they share files, a sandbox merges the two |
| 274 | commits and pushes nothing, and reports the files that |
| 275 | conflict. Meanwhile the box says **Checking whether this merges cleanly**, |
| 276 | and the merge button waits. Probes are charged as runner minutes; each |
| 277 | pair of commits is probed once, and a repository runs at most |
| 278 | three at a time, the rest following in turn. |
| 279 | |
| 280 | A pull request that conflicts shows **This branch has conflicts that must |
| 281 | be resolved**, the conflicting files, each linked to its diff, and how to |
| 282 | resolve them: |
| 283 | |
| 284 | - **Resolve in the browser.** Coming soon. |
| 285 | - **On the command line.** The box lists the commands, each with a copy |
| 286 | button. For a pull request from a branch: |
| 287 | |
| 288 | ```sh |
| 289 | git fetch origin |
| 290 | git checkout my-branch |
| 291 | git merge origin/main |
| 292 | # fix each conflicting file, then |
| 293 | git add -A && git commit --no-edit |
| 294 | git push origin my-branch |
| 295 | ``` |
| 296 | |
| 297 | For a pull request in its own fork, clone the fork and pull `main` into |
| 298 | it instead: |
| 299 | |
| 300 | ```sh |
| 301 | git clone https://g1t.sh/pulls/<id>.git && cd <id> |
| 302 | git pull --no-rebase https://g1t.sh/<owner>/<repo>.git main |
| 303 | ``` |
| 304 | |
| 305 | While it conflicts, it cannot be merged or added to the |
| 306 | [merge queue](/guides/merge-queue/), and the merge button says so. Once the |
| 307 | fix is pushed, g1t works it out again. |
| 308 | |
| 309 | A pull request that only has fallen behind its target, without conflicts, |
| 310 | still merges: merging brings it up to date first, unless the repository |
| 311 | requires pull requests to be up to date. |
| 312 | |
| 313 | ## Catching up |
| 314 | |
| 315 | When the target branch has moved, the merge box says **main has moved since |
| 316 | this was made**. Whoever can push to the pull request (whoever opened it, |
| 317 | for one in its own fork; anyone with the Write |
| 318 | [role](/guides/access-and-roles/) or higher, for a branch) can |
| 319 | press **Catch up with main now** when the two changed different files. |
| 320 | g1t merges `main` in itself, in a few seconds. The merge commit is named |
| 321 | **Merge main into *branch***, has the pull request's head and `main`'s |
| 322 | head as its parents, and is authored and pushed as you. The box then says |
| 323 | **Brought up to date with main**, and the workflows run again on the new |
| 324 | commit, as after any push. |
| 325 | |
| 326 | The merge is pushed only if the pull request's branch is still where it |
| 327 | was when the catch-up started. If someone pushed to it meanwhile, the |
| 328 | catch-up stops with nothing lost, and you can press it again. |
| 329 | |
| 330 | When both changed some of the same files, merge `main` in yourself, with |
| 331 | the commands under [conflicts](#conflicts). |
| 332 | |
| 333 | ## From the API |
| 334 | |
| 335 | `GET /repos/{owner}/{name}/pulls/{number}` returns, besides the pull request: |
| 336 | |
| 337 | | Field | What it is | |
| 338 | | --- | --- | |
| 339 | | `statuses` | What each workflow run, and anything else that reports statuses, said about its head, with a link to the run. | |
| 340 | | `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. | |
| 341 | | `checks` | The latest record against its head from g1t itself, such as the merge queue taking it out, with `earlier_checks` before it. | |
| 342 | | `mergeable` | `clean`, `conflicting`, `checking` or `unknown`. | |
| 343 | | `conflicts` | When conflicting, the files that conflict. | |
| 344 | | `behind` | Whether its target has moved on without it. | |
| 345 | | `reviewers`, `team_reviewers` | The people and the [teams](/guides/teams/#review-requests) asked to review it. | |
| 346 | | `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. | |
| 347 | |
| 348 | A coding agent sees the same through the `pull_request` tool's `get` |
| 349 | action. |