Skip to content
GitmoapAPIBeta
Reviewmerge-requests
GET/repositories/{repo_id}/merge-requests/{mr_id}/merge-check

Check merge status for a merge request

merge_check
  • merge_request:read
    A token needs the merge_request:read scope: View merge requestsGranted by mcp_agent, mcp_agent_write, read_api, read_repository, write_api, write_repository.Every operation this scope unlocks

Lists every requirement the merge request must meet before it can merge — approvals, resolved threads, checks, the draft flag, a merge request below it in a stack — and whether each is met. A merge stops at the first unmet requirement; this names all of them.

Parameters

Path
  • repo_idRepositoryId (string · uuid)Repository ID
  • mr_idMergeRequestId (integer · int64)Merge request ID

Responses

200Merge check resultapplication/json
  • checksarray of MergeCheckItem
    • The MergeCheckItem schema
    • checkstring
    • statusMergeCheckStatuspassedfailed
    • blockingbooleanoptionalWhether this check failing stops the merge. false for an advisory check — pipeline_stale and restack_required — which reports something worth knowing and never blocks; mergeable is every blocking check passing.
    • caller_levelAccessLevelguestreporterdevelopermaintainerowneror nulloptional
    • evaluated_target_shastring or nulloptionalThe target tip a pipeline_stale run was evaluated against — the evidence the check is reporting on, so "stale" is inspectable rather than merely asserted.
    • messagestring or nulloptional
    • missing_approvalsarray of string or nulloptional
    • pipeline_run_idPipelineRunId (string · uuid) or nulloptionalThe run a client should be sent to first, when the check read one: for pipeline_result the first pipeline's run not to have passed, else the first; for pipeline_stale, the first stale run.
    • pipeline_stateMrPipelineStatependingrunningfailedpassedemptyor nulloptionalFor pipeline_result: the verdict over pipelines, the same value GET …/merge-requests/{mr_id}/pipelines reports as state. A failed item with no pipelines is otherwise three different answers — not decided yet, nothing applies, or the evaluation was refused — and only this and pipelines_evaluated tell them apart without reading message.
    • pipelinesarray of MrPipelineEntry or nulloptionalFor pipeline_result: every pipeline that applies to the merge request's head and where it stands. For pipeline_stale: each one whose run was tested against a target that has since moved.
      • The MrPipelineEntry schema
      • pipeline_idPipelineId (string · uuid)The pipeline.
      • pipeline_namestringThe pipeline's name.
      • stalebooleanThe target branch has moved since the run was tested against it, so its result no longer describes what will land. Never blocks a merge on its own.
      • stateMrPipelineStatependingrunningfailedpassedemptyWhere this pipeline stands at the head.
      • buildMrBuildTargetmerge_resultsourceor nulloptionalWhich commit a merge-request run built: the merge result, or the source branch's tip.
      • commit_shastring or nulloptionalThe commit the run built — the merge result or the source tip, per build — which is the commit approve_pipeline_run names. Absent when no run has started.
      • evaluated_target_shastring or nulloptionalThe target branch's tip the run was tested against, for a merge-request run.
      • kindTriggerKindpushmerge_requesttagschedulemanualor nulloptionalWhat started the run: merge_request for a run started for this merge request, push or manual for a run of the head commit on its own.
      • pipeline_run_idPipelineRunId (string · uuid) or nulloptionalThe run that decides it: the pipeline's latest run that tested the head, preferring one started for this merge request. Absent when none has started.
      • refusalTriggerOutcomematchedno_trigger_matchnot_registered_at_refdraftauthority_deniedauthority_unresolvableauthority_revokedquota_exhaustedloop_guardsupersededprovider_validation_failedconnection_resolution_faileddefinition_invalidalready_triggeredmerge_conflictor nulloptionalWhy the pipeline did not start, when it applied and could not — a quota, a definition that does not resolve, a merge conflict. Absent when it started or has yet to.
      • statusPipelineStatusrunningsucceededsucceeded_with_warningsfailedtimed_outcancelledor nulloptionalThat run's status.
      • trustTriggerTrusttrusteduntrustedor nulloptionalWhether the run's code was trusted with the repository's connections and secrets. An untrusted run's result was reached without them, and a person approving commit_sha starts a trusted run that replaces it here. Absent when no run has started.
    • pipelines_evaluatedboolean or nulloptionalFor pipeline_result: whether the trigger engine has decided which pipelines apply to the head. false is the few seconds after a push, when the check waits rather than judges.
    • receivedinteger · int32 or nulloptional0–∞
    • requiredinteger · int32 or nulloptional0–∞
    • required_levelAccessLevelguestreporterdevelopermaintainerowneror nulloptional
    • rulesarray of ApprovalRuleStanding or nulloptionalFor the approvals check: every approval rule that applies, with each recorded approval and whether it counts toward that rule.
      • The ApprovalRuleStanding schema
      • approvalsarray of ApprovalStandingEvery recorded approval, with whether it counts toward this rule.
      • namestring
      • receivedinteger · int320–∞Distinct approvals that count.
      • requiredinteger · int320–∞
      • rule_idApprovalRuleId (string · uuid)
      • satisfiedboolean
    • stack_mr_iidinteger · int64 or nulloptional0–∞The iid of the related stack member for the downstack_unmerged / restack_required checks.
    • unresolved_threadsinteger · int32 or nulloptional0–∞
    • unverified_criteriaarray of string or nulloptionalThe acceptance criteria that are not green at the MR head, for the issue_criteria check.
  • commits_aheadinteger · int320–∞
  • commits_behindinteger · int320–∞
  • has_conflictsboolean
  • mergeableboolean
  • source_branch_existsboolean
  • source_shastring
  • target_shastring
  • conflictsConflictSummary or nulloptionalWhen the branches conflict: how many files, whether they can be resolved in the browser, and whether you may resolve them, with the reason when you may not. Absent when the branches merge cleanly.
    • The ConflictSummary schema
    • file_countinteger · int320–∞How many files conflict.
    • resolvable_in_browserbooleanWhether they can all be resolved in the browser; when not, they are resolved with git.
    • viewer_can_resolvebooleanWhether the caller may resolve them: resolving pushes a merge commit to the merge request's branch, so this is whether they may push there.
    • resolve_refusalstring or nulloptionalWhy not, when they may not.
200 exampleSynthesized example
{
"checks": [
{
"check": "check-012c",
"status": "passed"
},
{
"check": "check-bff5",
"status": "passed"
}
],
"commits_ahead": 3,
"commits_behind": 7,
"has_conflicts": false,
"mergeable": true,
"source_branch_exists": false,
"source_sha": "373049c7a3cf06156010f2617ffe27b3259fe33b",
"target_sha": "1f33c7db7c35887e68f4f59ecc94da30ef91c7a1",
"conflicts": {
"file_count": 5,
"resolvable_in_browser": false,
"viewer_can_resolve": false,
"resolve_refusal": "resolve-refusal-353c"
}
}
400Bad request — a path parameter is not a well-formed value of its typeapplication/json
Error codes
  • BAD_REQUESTThe request is malformed: a parameter or a body field is not a well-formed value of its type
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
400 exampleSynthesized example
{
"error": {
"code": "code-3544",
"message": "Pin a page's payload to the build that rendered it"
}
}
401Unauthenticated — no credential, or an invalid oneapplication/json
Error codes
  • UNAUTHORIZEDNo credential was sent, or the one sent is invalid, expired or revoked
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
401 exampleSynthesized example
{
"error": {
"code": "code-34e8",
"message": "Inline scalar newtypes but keep their brand"
}
}
403Forbidden — the caller's access level or token scope is insufficientapplication/json
Error codes
  • FORBIDDENYou are signed in but may not do this here; reason names the permission or the rule that refused it
  • INSUFFICIENT_SCOPEThe access token lacks the scope this operation needs; required_scope names it
  • PERMISSION_REQUIREDYou need a permission you do not hold here; the message names it
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
403 exampleSynthesized example
{
"error": {
"code": "code-f3fd",
"message": "Pin a page's payload to the build that rendered it"
}
}
404Not foundapplication/json
Error codes
  • NOT_FOUNDThe resource does not exist — or exists and you cannot see it: a private resource you have no access to answers exactly as an absent one does
  • errorErrorBody
    • The ErrorBody schema
    • codestringThe coarse category, tied to the status: NOT_FOUND, CONFLICT, INSUFFICIENT_SCOPE. Every error has one; the API reference's error catalogue lists them all.
    • messagestringWhat went wrong, for a person. Written to be read, not parsed: match on reason or code.
    • fieldstring or nulloptionalOn a 400 that refused one field's value, the field, as its JSON path: email, items[0].name. Put the message under that input. Absent on every other error.
    • reasonstring or nulloptionalThe specific code, when the error has one: LAST_ORGANIZATION_OWNER, BRANCH_PROTECTED. The message starts with it too. Match on this when it is present, and on code otherwise.
    • required_scopestring or nulloptionalThe scope the access token was missing, on INSUFFICIENT_SCOPE.
    • violationsanyoptionalPresent on the structured-validation errors (PROVIDER_VALIDATION_FAILED per-node, PIPELINE_VALIDATION_FAILED DAG): a JSON array of the offending elements, so a caller can fix every one in a single round-trip. Absent (omitted) on every other error.
404 exampleSynthesized example
{
"error": {
"code": "code-dcdf",
"message": "Inline scalar newtypes but keep their brand"
}
}

CLI

gitmoap mr merge-check

  • --repo-ididRepository ID (id or owner/repo path)
  • --mr-ididMerge request ID

Used in these guides