| 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, 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 | A pull request g1t made shows **g1t** as its author and **requested by** |
| 12 | the person who asked for it. That person can manage it as its author could, |
| 13 | and cannot approve it; see |
| 14 | [who a pull request is for](/guides/working-with-g1t/#who-a-pull-request-is-for). |
| 15 | |
| 16 | ## Checks |
| 17 | |
| 18 | A pull request's checks are the statuses reported on its head commit. Most |
| 19 | come from the repository's [workflows](/guides/actions/): every workflow |
| 20 | that runs on `pull_request` runs on every pull request's head, whoever |
| 21 | opened it, a person or an agent, and reports a check named after the |
| 22 | workflow. A workflow named `CI` reports the check `CI`; its status context |
| 23 | is `CI / pull_request`, the workflow's name and the event it ran for. Other |
| 24 | parts of g1t report under their own names, such as `g1t / deploy` (or |
| 25 | `g1t / deploy (<project>)`) for a [deployment](/guides/deployments/), and |
| 26 | your own CI and integrations report statuses and check runs through the |
| 27 | API: see [Checks](/guides/checks/). |
| 28 | |
| 29 | Which checks a merge needs is up to the repository: its |
| 30 | [required status checks](#required-status-checks). The merge box lists |
| 31 | those first: |
| 32 | |
| 33 | ```text |
| 34 | Required checks: 1 of 2 passing |
| 35 | CI failing Details |
| 36 | Lint passing Details |
| 37 | ``` |
| 38 | |
| 39 | Each required check is **passing**, **failing**, **running**, or |
| 40 | **expected**, "waiting for status to be reported", when nothing has |
| 41 | reported it on the head commit yet. **Details** opens the run that |
| 42 | reported it. Below them are all the other checks, workflow runs job by job, |
| 43 | each with its state and how long it took. A check that is not required is |
| 44 | shown, but never holds a merge. |
| 45 | |
| 46 | A workflow job's **Details** opens its log on the run's page, where every |
| 47 | step's output is kept. |
| 48 | |
| 49 | A closed or merged pull request keeps a checks section in its conversation: |
| 50 | its head commit's workflow runs, job by job, as they ended, each with |
| 51 | **Details** to its log. It is there to read; nothing in it can be re-run, |
| 52 | and it says nothing about merging. |
| 53 | |
| 54 | ### Other attempts at the same issue |
| 55 | |
| 56 | When an issue has more than one pull request, for example because two |
| 57 | agents each tried it, every one of them shows **Other attempts at #N**: the |
| 58 | pull requests for that issue side by side, this one first. Each row has its |
| 59 | state (open, merged, or closed because another was merged instead), its |
| 60 | head commit's checks, where its review stands, its size, and the files it |
| 61 | changes that this one changes too. Pull requests for the same issue are |
| 62 | alternatives, so they are not listed under **Other work is changing the |
| 63 | same files**; that box is for work on other issues, which will collide. |
| 64 | |
| 65 | ### Running them again |
| 66 | |
| 67 | People with the Write [role](/guides/access-and-roles/) or higher can press |
| 68 | **Re-run failed jobs** on a workflow run that failed, to run its failed jobs |
| 69 | again on the same commit. Every push to the pull request runs its workflows |
| 70 | again on the new head. |
| 71 | |
| 72 | ### A repository with no checks |
| 73 | |
| 74 | When a repository has no workflows, the merge box says **This repository |
| 75 | has no checks**: nothing proves a change works, for people or for agents. |
| 76 | **Add CI** writes a starter workflow for you; see |
| 77 | [add CI](/guides/actions/#add-ci). The same offer is on the |
| 78 | **Branches and merging** settings page and the **Actions** page. |
| 79 | |
| 80 | ## Required status checks |
| 81 | |
| 82 | What a pull request needs before it merges is set by the |
| 83 | [rulesets](/guides/rules/) that cover the branch it merges into, the |
| 84 | repository's and its workspace's. They hold for every pull request into |
| 85 | that branch, a person's or an agent's. Someone with the Admin |
| 86 | [role](/guides/access-and-roles/) sets them under the |
| 87 | repository's **Settings → Rules**: |
| 88 | |
| 89 | | Rule | What it does | |
| 90 | | --- | --- | |
| 91 | | 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 an agent's approval counts, whether approvals before the latest push count, and whether [code owners](/guides/codeowners/#require-review-from-code-owners) must approve. | |
| 92 | | 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. | |
| 93 | | Require the merge queue | See [merge queue](/guides/merge-queue/). | |
| 94 | | Require deployments to succeed | A pull request's head must have deployed to these environments. | |
| 95 | |
| 96 | [Rules](/guides/rules/#rules) lists every rule, including those for |
| 97 | agents' changes, confidence, cost, sensitive paths and merge windows. |
| 98 | The merge box on a pull request lists each rule it does not meet yet, with |
| 99 | the ruleset it comes from and what to do about it. |
| 100 | |
| 101 | ### Choosing the checks |
| 102 | |
| 103 | **Require status checks to pass** offers the check names reported on the |
| 104 | repository's commits in the last 30 days. Pick from them, or type a name |
| 105 | that has not reported yet. A check can be pinned to the integration that |
| 106 | must report it, such as workflows or deployments. |
| 107 | |
| 108 | A required check is met by a status of that name on the pull request's head, |
| 109 | whatever event reported it: |
| 110 | |
| 111 | | What reported it | What the merge does | |
| 112 | | --- | --- | |
| 113 | | A status that failed | Refused: "The required check CI failed." | |
| 114 | | A status still pending | Held: "The required check CI has not finished." | |
| 115 | | Nothing yet | Held: "The required check CI has not reported on its latest commit." | |
| 116 | | Success | Allowed | |
| 117 | |
| 118 | The same rule holds wherever a pull request merges: the merge button, |
| 119 | [`merge_pull_request`](/reference/api/pull-requests/merge-pull-request/), |
| 120 | a g1t agent's [automatic merge](/guides/working-with-g1t/#merging-automatically) |
| 121 | and the [merge queue](/guides/merge-queue/). Where the rule lets a merger bypass the |
| 122 | required checks, the merge button has a **bypass** box, and the API takes |
| 123 | `ignore_checks: true`. |
| 124 | |
| 125 | A check that only exists once a workflow has run, such as `CI` from a |
| 126 | workflow added in a pull request, appears in the list after that workflow |
| 127 | has run once. |
| 128 | |
| 129 | ### From the API |
| 130 | |
| 131 | ```sh |
| 132 | curl https://api.g1t.sh/repos/<workspace>/<repo>/check-names \ |
| 133 | -H "Authorization: Bearer $G1T_TOKEN" |
| 134 | ``` |
| 135 | |
| 136 | [`list_check_names`](/reference/api/repositories/list-check-names/) |
| 137 | returns the names seen in the last 30 days, most recent first, each as |
| 138 | `{name, events, last_seen}`. It needs the `repo:read` scope. |
| 139 | |
| 140 | ```sh |
| 141 | curl -X PATCH https://api.g1t.sh/repos/<workspace>/<repo>/settings \ |
| 142 | -H "Authorization: Bearer $G1T_TOKEN" \ |
| 143 | -H "Content-Type: application/json" \ |
| 144 | -d '{"required_checks": ["CI", "g1t / deploy"]}' |
| 145 | ``` |
| 146 | |
| 147 | [`update_repo_settings`](/reference/api/repositories/update-repo-settings/) |
| 148 | takes `required_checks`, which replaces the whole list, along with |
| 149 | `required_approvals`, `count_agent_approvals`, `require_up_to_date`, |
| 150 | `merge_queue`, `allow_ignoring_checks` and `require_code_owner_review`; |
| 151 | [`get_repo_settings`](/reference/api/repositories/get-repo-settings/) |
| 152 | returns them. On the MCP server they are the `repository` tool's |
| 153 | `check_names`, `get_settings` and `update_settings` actions. They read and |
| 154 | write the "Default branch protection" ruleset; [rulesets](/guides/rules/#from-the-api) |
| 155 | have routes of their own. |
| 156 | |
| 157 | ## Reviewers |
| 158 | |
| 159 | Ask people to review a pull request in the **Reviewers** box on its page, |
| 160 | by username. You can also ask a [team](/guides/teams/), as |
| 161 | `@workspace/team`: everyone in it is asked, or, with the team's |
| 162 | [review assignment](/guides/teams/#review-assignment) on, g1t picks who, |
| 163 | and they are listed beside the team. Asking needs the Triage |
| 164 | [role](/guides/access-and-roles/) or higher, or being the pull request's |
| 165 | author. Nobody is asked to review their own pull request. |
| 166 | |
| 167 | When the repository has a [CODEOWNERS file](/guides/codeowners/), the |
| 168 | owners of the files a pull request changes are asked by themselves, and |
| 169 | the pull request shows **Code owners**: who owns which files and whose |
| 170 | approval is still needed. |
| 171 | |
| 172 | Through the API, `POST /repos/{owner}/{name}/pulls/{number}/requested_reviewers` |
| 173 | takes `reviewers` (usernames) and `team_reviewers` (teams, as |
| 174 | `workspace/team` or the team's slug), and adds them to whoever is asked |
| 175 | already; `DELETE` on the same route takes requests away. On |
| 176 | the MCP server they are the `pull_request` tool's `request_reviewers` and |
| 177 | `remove_requested_reviewers` actions. |
| 178 | |
| 179 | ## Agent reviews |
| 180 | |
| 181 | Your workspace's [agents](/guides/agents/) comment on issues and pull |
| 182 | requests, and review pull requests, as themselves: a comment from Margo |
| 183 | shows her pixel face, her name with an **Agent** badge (linked to |
| 184 | [her page](/guides/agents/#the-agents-page)), and **on behalf of @ana**, |
| 185 | the person she was working for. |
| 186 | |
| 187 | An agent's review is **advisory**. It shows its verdict (approved, |
| 188 | requested changes, or reviewed, for one that only comments) with an |
| 189 | **Advisory** chip, and in the summary of reviews at the top of the pull |
| 190 | request, but it counts toward nothing: |
| 191 | |
| 192 | - It never satisfies the approvals a branch requires, nor a |
| 193 | [code owner's](/guides/codeowners/) approval. A person still approves. |
| 194 | - A request for changes from an agent never blocks a merge and never sends |
| 195 | g1t back to revise; a person's does. |
| 196 | - It is never counted as a review on the profile of the person it acted |
| 197 | for. |
| 198 | |
| 199 | What an agent may do on a pull request is capped by the person it acts |
| 200 | for: they must be able to read the repository and comment on it, as if |
| 201 | they wrote it themselves, and an archived repository refuses it. Beyond |
| 202 | that: |
| 203 | |
| 204 | - An agent doesn't review a draft, nor a closed or merged pull request. It |
| 205 | can still comment on them. |
| 206 | - An agent writes at most 5 comments and reviews on one issue or pull |
| 207 | request an hour. |
| 208 | - Mentioning `@g1t` in an agent's comment doesn't put g1t to work, and an |
| 209 | agent can't give commands on [dependency updates](/guides/dependency-updates/). |
| 210 | |
| 211 | The person it acted for can edit and delete what the agent wrote, as its |
| 212 | author could, and so can anyone with the Maintain |
| 213 | [role](/guides/access-and-roles/) or higher. A review stays, as a |
| 214 | person's does. |
| 215 | |
| 216 | People mentioned in an agent's comment, and everyone subscribed to the |
| 217 | pull request, hear of it in their [notifications](/guides/notifications/) as from |
| 218 | **Margo (agent)**, with "(advisory)" on a review. It publishes |
| 219 | `comment.created` as a person's comment does, with `agent` (its `id`, |
| 220 | `handle`, `display_name` and `avatar_seed`), `acting_for`, and for a |
| 221 | review `advisory: true` and the verdict, so [webhooks](/guides/webhooks/) |
| 222 | see it too; its `actor` is the person it acted for. Through the API and |
| 223 | the MCP server, each such comment has `agent`, `acting_for` and, for a |
| 224 | review, `advisory: true`; its `author` is the agent, of kind `agent`. |
| 225 | |
| 226 | ## Drafts, closing and reopening |
| 227 | |
| 228 | A draft is still being worked on: it can be reviewed, but it cannot merge |
| 229 | until it is marked ready for review. Its author, whoever asked g1t for it, |
| 230 | and anyone with the Triage [role](/guides/access-and-roles/) or higher can |
| 231 | move a pull request between these states. An |
| 232 | [archived](/guides/managing-repositories/) repository refuses all of them. |
| 233 | |
| 234 | ### Open a draft |
| 235 | |
| 236 | When you open a pull request from a branch, choose **Open as draft** to |
| 237 | say it isn't ready yet. Push to the branch as often as you like; select |
| 238 | **Mark ready for review** when it is. Routines that review pull requests |
| 239 | (an agent's routine that runs when a pull request is ready for review) run |
| 240 | then, not before. Through the API, send `"draft": true` when you open it. |
| 241 | |
| 242 | ### Convert to a draft |
| 243 | |
| 244 | To take a pull request that is ready for review back to a draft, select |
| 245 | **Convert to draft** under the comment box. It leaves the |
| 246 | [merge queue](/guides/merge-queue/) if it is in it, and a merge that was |
| 247 | waiting for it to catch up is called off. Mark it ready again with |
| 248 | **Mark ready for review**. |
| 249 | |
| 250 | Only an open pull request can be converted; a draft, a closed or a merged |
| 251 | one is refused with `409`. |
| 252 | |
| 253 | ### Reopen a pull request |
| 254 | |
| 255 | To open a closed pull request again, select **Reopen pull request** under |
| 256 | the comment box. It comes back as it was when it was closed: a draft if it |
| 257 | was closed as a draft, otherwise ready for review. Its checks and whether |
| 258 | it merges cleanly are worked out again. |
| 259 | |
| 260 | A merged pull request cannot be reopened. Neither can one from a branch of |
| 261 | the repository whose branch was deleted: push the branch again first. |
| 262 | |
| 263 | ### From the API |
| 264 | |
| 265 | | To | Call | MCP | |
| 266 | | --- | --- | --- | |
| 267 | | Convert to a draft | `POST /repos/{owner}/{name}/pulls/{number}/draft` | `pull_request` with `"action": "draft"` | |
| 268 | | Close | `POST /repos/{owner}/{name}/pulls/{number}/close`, or `PATCH /repos/{owner}/{name}/pulls/{number}` with `"state": "closed"` | `pull_request` with `"action": "close"` | |
| 269 | | Reopen | `POST /repos/{owner}/{name}/pulls/{number}/reopen`, or `PATCH /repos/{owner}/{name}/pulls/{number}` with `"state": "open"` | `pull_request` with `"action": "reopen"` | |
| 270 | |
| 271 | Each answers with the pull request as it is now. Converting publishes |
| 272 | `pull.converted_to_draft` and reopening publishes `pull.reopened`, with the |
| 273 | head commit in `commit`; both reach [webhooks](/guides/webhooks/) and can |
| 274 | start [workflows](/guides/actions/). |
| 275 | |
| 276 | ## Editing and deleting comments |
| 277 | |
| 278 | You can edit and delete your own comments on issues and pull requests. |
| 279 | Anyone with the Maintain [role](/guides/access-and-roles/) or higher can |
| 280 | edit and delete anyone's. |
| 281 | |
| 282 | - To edit a comment, select **Edit** under it, change the text and select |
| 283 | **Save**. The comment shows **edited** beside its time. |
| 284 | - To delete a comment, select **Delete** under it and confirm. It is |
| 285 | removed for everyone and cannot be brought back. |
| 286 | |
| 287 | A review that approved or requested changes can be edited but not deleted, |
| 288 | so its verdict stays on record. What an |
| 289 | [agent wrote as itself](#agent-reviews) is the person it acted for's to |
| 290 | edit and delete. The notes in the timeline of what happened, |
| 291 | such as "closed this", cannot be edited or deleted. |
| 292 | |
| 293 | Through the API, `PATCH /repos/{owner}/{name}/issues/comments/{comment_id}` |
| 294 | with `body` edits a comment and answers with it, and |
| 295 | `DELETE /repos/{owner}/{name}/issues/comments/{comment_id}` deletes it and |
| 296 | answers `204`. Both work for comments on issues and on pull requests; each |
| 297 | comment's `id` is in `GET /repos/{owner}/{name}/issues/{number}` and |
| 298 | `GET /repos/{owner}/{name}/pulls/{number}`. On the MCP server they are the |
| 299 | `issue` tool's `edit_comment` and `delete_comment` actions. Editing |
| 300 | publishes `comment.edited`, with what the comment said before in |
| 301 | `changes.body.from`; deleting publishes `comment.deleted`, with the comment |
| 302 | as it was in `comment`. |
| 303 | |
| 304 | ## Conflicts |
| 305 | |
| 306 | g1t works out whether a pull request merges cleanly into its target before |
| 307 | anyone tries to merge it, and again whenever either side moves: a push to |
| 308 | the pull request, or anything landing on the target branch. |
| 309 | |
| 310 | 1. **Without a sandbox.** g1t compares the files the pull request changed |
| 311 | since it and the target last agreed with the files the target changed |
| 312 | since then. If they share none, the merge cannot conflict, and that is |
| 313 | the answer. |
| 314 | 2. **With a short probe.** If they share files, a sandbox merges the two |
| 315 | commits without an agent and pushes nothing, and reports the files that |
| 316 | conflict. Meanwhile the box says **Checking whether this merges cleanly**, |
| 317 | and the merge button waits. Probes are metered as sandbox time; each |
| 318 | pair of commits is probed once, and a repository runs at most |
| 319 | three at a time, the rest following in turn. |
| 320 | |
| 321 | A pull request that conflicts shows **This branch has conflicts that must |
| 322 | be resolved**, the conflicting files, each linked to its diff, and three |
| 323 | ways to resolve them: |
| 324 | |
| 325 | - **Resolve with g1t.** g1t merges the target branch in, |
| 326 | resolves the conflicts keeping what both sides meant, and pushes the |
| 327 | result. It is told which files conflict. Available to whoever can push to |
| 328 | the pull request: for a pull request's fork, whoever opened it (whoever |
| 329 | asked g1t for one it made); for a branch, anyone with the Write role or |
| 330 | higher. |
| 331 | - **Resolve in the browser.** Coming soon. |
| 332 | - **On the command line.** The box lists the commands, each with a copy |
| 333 | button. For a pull request from a branch: |
| 334 | |
| 335 | ```sh |
| 336 | git fetch origin |
| 337 | git checkout my-branch |
| 338 | git merge origin/main |
| 339 | # fix each conflicting file, then |
| 340 | git add -A && git commit --no-edit |
| 341 | git push origin my-branch |
| 342 | ``` |
| 343 | |
| 344 | For a pull request in its own fork, clone the fork and pull `main` into |
| 345 | it instead: |
| 346 | |
| 347 | ```sh |
| 348 | git clone https://g1t.sh/pulls/<id>.git && cd <id> |
| 349 | git pull --no-rebase https://g1t.sh/<owner>/<repo>.git main |
| 350 | ``` |
| 351 | |
| 352 | While it conflicts, it cannot be merged or added to the |
| 353 | [merge queue](/guides/merge-queue/), and the merge button says so. Once the |
| 354 | fix is pushed, g1t works it out again. |
| 355 | |
| 356 | A pull request that only has fallen behind its target, without conflicts, |
| 357 | still merges: merging brings it up to date first, unless the repository |
| 358 | requires pull requests to be up to date. |
| 359 | |
| 360 | ## Catching up |
| 361 | |
| 362 | When the target branch has moved, the merge box says **main has moved since |
| 363 | this was made**. Whoever can push to the pull request (whoever opened it, |
| 364 | or asked g1t for it, for one in its own fork; anyone with the Write |
| 365 | [role](/guides/access-and-roles/) or higher, for a branch) can |
| 366 | press **Catch up with main now**: |
| 367 | |
| 368 | 1. **When the two changed different files**, g1t merges `main` in itself, |
| 369 | in a few seconds. The merge commit is named **Merge main into |
| 370 | *branch***, has the pull request's head and `main`'s head as its |
| 371 | parents, and is authored and pushed as you. The box then says **Brought |
| 372 | up to date with main**, and the workflows run again on the |
| 373 | new commit, as after any push. |
| 374 | 2. **When both changed some of the same files**, a sandbox merges `main` in |
| 375 | with git, and [g1t](/guides/working-with-g1t/) resolves any conflict. |
| 376 | The box says what is happening (**g1t is resolving conflicts with |
| 377 | main** when the merge is known to conflict) with the run's live step and |
| 378 | how long it has taken. It usually takes about a minute. When the result |
| 379 | is pushed, the box shows the pull request up to date; if the run fails, |
| 380 | or nothing has been pushed after five minutes, the box says so and |
| 381 | offers **Try again**. Nothing is pushed by a run that fails. |
| 382 | |
| 383 | Either way the merge is pushed only if the pull request's branch is still |
| 384 | where it was when the catch-up started. If someone pushed to it meanwhile, |
| 385 | the catch-up stops with nothing lost, and you can press it again. |
| 386 | |
| 387 | The second case needs g1t's agent enabled for the workspace and is |
| 388 | [charged](/guides/usage-and-billing/#what-is-charged) as agent work; the |
| 389 | first is not. |
| 390 | |
| 391 | A pull request [g1t](/guides/working-with-g1t/) opened that is found to conflict |
| 392 | is sent back to resolve it by itself, before it is ready. |
| 393 | |
| 394 | ## From the API |
| 395 | |
| 396 | `GET /repos/{owner}/{name}/pulls/{number}` returns, besides the pull request: |
| 397 | |
| 398 | | Field | What it is | |
| 399 | | --- | --- | |
| 400 | | `statuses` | What each workflow run, and anything else that reports statuses, said about its head, with a link to the run. | |
| 401 | | `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. | |
| 402 | | `checks` | The latest record against its head from g1t itself, such as the merge queue taking it out, with `earlier_checks` before it. | |
| 403 | | `mergeable` | `clean`, `conflicting`, `checking` or `unknown`. | |
| 404 | | `conflicts` | When conflicting, the files that conflict. | |
| 405 | | `behind` | Whether its target has moved on without it. | |
| 406 | | `reviewers`, `team_reviewers` | The people and the [teams](/guides/teams/#review-requests) asked to review it. | |
| 407 | | `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. | |
| 408 | |
| 409 | An agent sees the same through the `pull_request` tool's `get` action. |