dev.knotless.getMergeStatus

lexicons.knotless.dev

Documentation

Whether an open pull can merge now, decided as `knotless merge` decides it, without merging: whether its head merges with its target branch as it is now, and, in a repository that names runners, whether each workflow that runs on it passed there. And what the account asking may do to it: merge it, queue it, retarget it or run its checks again. Requires the session cookie the pages' login sets, or a service token from the caller's PDS, audience the appview's DID, for this method.

main query

Whether an open pull can merge now, decided as `knotless merge` decides it, without merging: whether its head merges with its target branch as it is now, and, in a repository that names runners, whether each workflow that runs on it passed there. And what the account asking may do to it: merge it, queue it, retarget it or run its checks again. Requires the session cookie the pages' login sets, or a service token from the caller's PDS, audience the appview's DID, for this method.

Parameters

pull string at-uri Required

The dev.knotless.pull record.

repo string at-uri Required

The repository's dev.knotless.repo record, as dev.knotless.getRepo takes it.

Output

Encodingapplication/json
base string Required

The commit its target branch is at, in hex.

checks string Required

Where its checks stand at its head merged with its base: pending for those not run there; none when the repository names no runners, so a merge waits for none, or when it conflicts.

Known values: passed, failed, running, pending, none
codeOwnersWarnings array Optional

The lines of the target branch's CODEOWNERS file that were skipped, and why: one naming a team, say.

conflicts array Optional

The files that conflict.

deletes string Optional

Its head branch, which merging deletes unless asked to keep it.

head string Required

The commit its head branch is at, in hex.

method string Required

How it would merge: a fast-forward when the base has not moved since its head branched off, else a merge commit; into a branch protected as linear, one squashed commit.

Known values: fastForward, merge, squash
queueBlocked string Optional

Why the merge queue would not land it yet, when this server knows: undelegated when no runner the repository names may push, so its queue lands through this server's gateway, and the owner has not delegated writes to it.

Known values: undelegated
queueOnly boolean Optional

Its target branch takes pulls only through the merge queue: queue it with dev.knotless.queuePull, as dev.knotless.mergePull refuses it. Absent is false.

reason string Optional

Why it cannot merge now, in the words a merge would refuse it with; and when the account asking may not merge it, that too.

reviews string Optional

Where its reviews stand against what its target branch's rule asks of them (dev.knotless.repo#reviews): none when the rule asks nothing of them, or when it conflicts.

Known values: passed, blocked, none
reviewsMissing array Optional

What its reviews lack, each as `knotless merge --check` lists it: `reviews 1 of 2`, `owners of web/: @alice or @bob`, `changes asked by @carol`.

reviewsUncounted array Optional

The approvals that do not count toward its target branch's rule, and why: `@dan's approval does not count: only the owner's and collaborators' approvals count`, or one of an earlier head when only approvals of its head as it is now count.

state string Required

clean when it can merge now; conflicting when its head does not merge with its base; blocked when its checks have not all passed, or it is not reviewed as its target branch's rule asks; draft, whatever else holds, while its author has not marked it ready.

Known values: clean, conflicting, blocked, draft

Errors

NotFound No such repository.
AuthenticationRequired No one asked: log in to the pages first.
Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Base URL for XRPC calls (e.g., https://api.bsky.social)
Parameters
The dev.knotless.pull record.
The repository's dev.knotless.repo record, as dev.knotless.getRepo takes it.
View raw schema 
{
  "description": "Whether an open pull can merge now, decided as `knotless merge` decides it, without merging: whether its head merges with its target branch as it is now, and, in a repository that names runners, whether each workflow that runs on it passed there. And what the account asking may do to it: merge it, queue it, retarget it or run its checks again. Requires the session cookie the pages' login sets, or a service token from the caller's PDS, audience the appview's DID, for this method.",
  "errors": [
    {
      "description": "No such repository.",
      "name": "NotFound"
    },
    {
      "description": "No one asked: log in to the pages first.",
      "name": "AuthenticationRequired"
    }
  ],
  "output": {
    "encoding": "application/json",
    "schema": {
      "properties": {
        "base": {
          "description": "The commit its target branch is at, in hex.",
          "type": "string"
        },
        "checks": {
          "description": "Where its checks stand at its head merged with its base: pending for those not run there; none when the repository names no runners, so a merge waits for none, or when it conflicts.",
          "knownValues": [
            "passed",
            "failed",
            "running",
            "pending",
            "none"
          ],
          "type": "string"
        },
        "codeOwnersWarnings": {
          "description": "The lines of the target branch's CODEOWNERS file that were skipped, and why: one naming a team, say.",
          "items": {
            "ref": "#note",
            "type": "ref"
          },
          "type": "array"
        },
        "conflicts": {
          "description": "The files that conflict.",
          "items": {
            "ref": "#conflict",
            "type": "ref"
          },
          "type": "array"
        },
        "deletes": {
          "description": "Its head branch, which merging deletes unless asked to keep it.",
          "type": "string"
        },
        "head": {
          "description": "The commit its head branch is at, in hex.",
          "type": "string"
        },
        "may": {
          "ref": "#permissions",
          "type": "ref"
        },
        "method": {
          "description": "How it would merge: a fast-forward when the base has not moved since its head branched off, else a merge commit; into a branch protected as linear, one squashed commit.",
          "knownValues": [
            "fastForward",
            "merge",
            "squash"
          ],
          "type": "string"
        },
        "queueBlocked": {
          "description": "Why the merge queue would not land it yet, when this server knows: undelegated when no runner the repository names may push, so its queue lands through this server's gateway, and the owner has not delegated writes to it.",
          "knownValues": [
            "undelegated"
          ],
          "type": "string"
        },
        "queueOnly": {
          "description": "Its target branch takes pulls only through the merge queue: queue it with dev.knotless.queuePull, as dev.knotless.mergePull refuses it. Absent is false.",
          "type": "boolean"
        },
        "reason": {
          "description": "Why it cannot merge now, in the words a merge would refuse it with; and when the account asking may not merge it, that too.",
          "type": "string"
        },
        "reviews": {
          "description": "Where its reviews stand against what its target branch's rule asks of them (dev.knotless.repo#reviews): none when the rule asks nothing of them, or when it conflicts.",
          "knownValues": [
            "passed",
            "blocked",
            "none"
          ],
          "type": "string"
        },
        "reviewsMissing": {
          "description": "What its reviews lack, each as `knotless merge --check` lists it: `reviews 1 of 2`, `owners of web/: @alice or @bob`, `changes asked by @carol`.",
          "items": {
            "ref": "#note",
            "type": "ref"
          },
          "type": "array"
        },
        "reviewsUncounted": {
          "description": "The approvals that do not count toward its target branch's rule, and why: `@dan's approval does not count: only the owner's and collaborators' approvals count`, or one of an earlier head when only approvals of its head as it is now count.",
          "items": {
            "ref": "#note",
            "type": "ref"
          },
          "type": "array"
        },
        "state": {
          "description": "clean when it can merge now; conflicting when its head does not merge with its base; blocked when its checks have not all passed, or it is not reviewed as its target branch's rule asks; draft, whatever else holds, while its author has not marked it ready.",
          "knownValues": [
            "clean",
            "conflicting",
            "blocked",
            "draft"
          ],
          "type": "string"
        }
      },
      "required": [
        "state",
        "checks",
        "method",
        "base",
        "head",
        "may"
      ],
      "type": "object"
    }
  },
  "parameters": {
    "properties": {
      "pull": {
        "description": "The dev.knotless.pull record.",
        "format": "at-uri",
        "type": "string"
      },
      "repo": {
        "description": "The repository's dev.knotless.repo record, as dev.knotless.getRepo takes it.",
        "format": "at-uri",
        "type": "string"
      }
    },
    "required": [
      "repo",
      "pull"
    ],
    "type": "params"
  },
  "type": "query"
}
conflict object

A file that both sides changed so that they do not merge.

Properties

path string Required

From the repository's root.

View raw schema 
{
  "description": "A file that both sides changed so that they do not merge.",
  "properties": {
    "path": {
      "description": "From the repository's root.",
      "type": "string"
    }
  },
  "required": [
    "path"
  ],
  "type": "object"
}
note object

A line of text about the pull's reviews.

Properties

text string Required

In plain words.

View raw schema 
{
  "description": "A line of text about the pull's reviews.",
  "properties": {
    "text": {
      "description": "In plain words.",
      "type": "string"
    }
  },
  "required": [
    "text"
  ],
  "type": "object"
}
permissions object

What the account asking may do to the pull: what its part in the repository lets it do, not whether that would work now. state and reason say that: a merge refuses a blocked pull, the owner's merge too, unless the owner forces it.

Properties

base boolean Required

Change its target branch: those who may close it.

force boolean Required

Merge it past its checks: the owner alone.

head boolean Required

Change its head branch: its author.

merge boolean Required

Merge it: the owner and collaborators.

queue boolean Required

Put it in the merge queue or take it out: those who may merge it, in a repository whose runners land a queue.

rerun boolean Required

Ask the runners to run its checks again: the owner, in a repository that names runners.

View raw schema 
{
  "description": "What the account asking may do to the pull: what its part in the repository lets it do, not whether that would work now. state and reason say that: a merge refuses a blocked pull, the owner's merge too, unless the owner forces it.",
  "properties": {
    "base": {
      "description": "Change its target branch: those who may close it.",
      "type": "boolean"
    },
    "force": {
      "description": "Merge it past its checks: the owner alone.",
      "type": "boolean"
    },
    "head": {
      "description": "Change its head branch: its author.",
      "type": "boolean"
    },
    "merge": {
      "description": "Merge it: the owner and collaborators.",
      "type": "boolean"
    },
    "queue": {
      "description": "Put it in the merge queue or take it out: those who may merge it, in a repository whose runners land a queue.",
      "type": "boolean"
    },
    "rerun": {
      "description": "Ask the runners to run its checks again: the owner, in a repository that names runners.",
      "type": "boolean"
    }
  },
  "required": [
    "merge",
    "force",
    "queue",
    "base",
    "head",
    "rerun"
  ],
  "type": "object"
}

Lexicon Garden

@