Forgejo and Gitea: merge when checks succeed, refused or not merged
Sending merge_when_checks_succeed: true to the merge API (POST /api/v1/repos/OWNER/REPO/pulls/NUMBER/merge) asks the server to merge the pull request once its checks pass. The server answers 201 with an empty body when it has scheduled the merge. All of the following was checked on October 24, 2026 in the current source of both (routers/api/v1/repo/pull.go, services/pull/check.go, services/automerge/automerge.go, models/pull/automerge.go). For the answers to an ordinary merge, see why the merge was refused.
What scheduling skips, and what still refuses it
- Skipped: the branch protection checks, such as required approvals, required status checks, requested changes and a branch behind its base. A scheduled merge waits for these.
- Still 405, as for an ordinary merge:
User not allowed to merge PR,Work in progress PRs cannot be merged,Please try again later(conflicts, or a pull request the server is still checking after a push), required signed commits, a merge style the repository does not allow, and an already merged pull request. A closed one answers 404. - 409
pull request is already scheduled to auto merge when checks succeed [pull_id: …](in English: a merge is already scheduled): one schedule per pull request. Thepull_idis the server's internal ID, not the pull request's number. The button on the web page replaces an earlier schedule; the API keeps it and refuses the new one. - 500 with an empty
message: the pull request depends on an issue or pull request that is still open. The merge check ends in the erroris blocked by an open dependency, which the API passes on as an internal error, with the message shown only to administrators. An ordinary merge answers the same once the other checks pass.
The server schedules the merge even when nothing is left to wait for.
When the scheduled merge happens
- In the background, once the required status checks of the head commit pass and then the ordinary merge checks pass too, approvals included, for the person who scheduled it. If that person may no longer merge, it is not merged.
- Gitea checks right after scheduling, so a pull request that already passes is merged a moment later.
- Forgejo does not check when you schedule. It checks when a successful commit status arrives for the head, when someone approves or a review is dismissed, and when it has finished checking the pull request after a push. A merge scheduled after the last check finished waits for the next of these.
- A schedule keeps no commit. Both servers take it without reading
head_commit_id(sent with it, it is not checked), and later merge the branch as it is then: commits pushed after you scheduled are merged too, once their checks pass. A push does not cancel the schedule. To keep new commits out, cancel the schedule first. - If the merge itself then fails, for example on conflicts git finds or a hook that refuses the push, both servers only write it to their log: nothing appears on the pull request (both sources mark this as a known gap). Forgejo has removed the schedule before trying, so it is gone. Gitea keeps it and tries again at the next check.
Cancelling it
DELETE /api/v1/repos/OWNER/REPO/pulls/NUMBER/merge answers 204 when it cancelled the scheduled merge, 404 when none is scheduled, and 403 user has no permission to cancel the scheduled auto merge when you did not schedule it and may not merge the pull request yourself.
What to do
- 405: fix what the message names (the work-in-progress prefix, the conflicts), then schedule again.
- 409 already scheduled: to change the merge style or message, cancel it with
DELETE, then schedule again. - 500 with no message: look at the pull request's dependencies, and close the open one or remove the dependency.
- Scheduled but not merged: check that the required checks passed and the approvals are there. On Forgejo, re-run a check or approve again to make it look; if it still does not merge, ask the server's administrator for the log, or merge it by hand.
Forgejo and Gitea pull requests in IntelliJ IDEA
Pull Request Inbox for Forgejo and Gitea, a plugin by Lesstep for JetBrains IDEs 2024.1 or later, shows a pull request's merge checks before you merge and merges the head commit you had on screen. While the checks still run, its Merge dialog offers to merge when the checks succeed, and says the pull request will be merged then when the server answers 201. From version 1.0.17, when the server refuses to schedule it (405), it no longer names approvals and failing checks, which a scheduled merge waits for: it says that the pull request must not be a work in progress or conflict, and that you must be allowed to merge into the branch. When a merge is already scheduled (409), it says that the earlier one stays; for a 500 with no message, that an open dependency blocks the pull request. From version 1.0.18, it checks before scheduling that the branch has not moved since you opened the pull request, and says so instead of scheduling; the Merge dialog and the notice after scheduling say that commits pushed until the checks pass are merged too, and that cancelling the schedule on the pull request's page stops it. Reading is free; approving, commenting and merging are Pro (US$1.50 a month, with a 30-day trial).
Forgejo, Gitea and Codeberg are names of their respective owners; IntelliJ IDEA is a trademark of JetBrains s.r.o. This page is not affiliated with or endorsed by the Forgejo project, Codeberg e.V., the Gitea project or JetBrains.
More: Forgejo and Gitea merge refused (405, 409) · Forgejo and Gitea required checks (missing, skipped, patterns) · Forgejo and Gitea branch update refused (403, 409, 422) · Forgejo and Gitea review refused (422) · 404 "The target couldn't be found." and "not found" · "token does not have at least one of required scope(s)" · Forgejo and Gitea search refused (400, 422) · Forgejo and Gitea pull request files (pages of 50, changed_files) · Forgejo and Gitea pull request plugins for IntelliJ IDEA, compared · 日本語