# dev.knotless.getMergeStatus

> Published by [lexicons.knotless.dev](https://lexicon.garden/identity/did:plc:yqsg7znbbhfmj3a2nrpnaerk)

✓ This is the authoritative definition for this NSID.

## Description

Whether an open pull can merge now, and what the account asking may do to it.

## Links

- [View on Lexicon Garden](https://lexicon.garden/lexicon/did:plc:yqsg7znbbhfmj3a2nrpnaerk/dev.knotless.getMergeStatus)
- [Documentation](https://lexicon.garden/lexicon/did:plc:yqsg7znbbhfmj3a2nrpnaerk/dev.knotless.getMergeStatus/docs)
- [Examples](https://lexicon.garden/lexicon/did:plc:yqsg7znbbhfmj3a2nrpnaerk/dev.knotless.getMergeStatus/examples)

## Definitions

### `dev.knotless.getMergeStatus#conflict`

**Type**: `object`

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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `path` | `string` | Yes | From the repository's root. |

### `dev.knotless.getMergeStatus`

**Type**: `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

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `pull` | `string` (at-uri) | Yes | The dev.knotless.pull record. |
| `repo` | `string` (at-uri) | Yes | The repository's dev.knotless.repo record, as dev.knotless.getRepo takes it. |

#### Output

**Encoding**: `application/json`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `base` | `string` | Yes | The commit its target branch is at, in hex. |
| `checks` | `string` | Yes | 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. |
| `codeOwnersWarnings` | `array` | No | The lines of the target branch's CODEOWNERS file that were skipped, and why: one naming a team, say. |
| `conflicts` | `array` | No | The files that conflict. |
| `deletes` | `string` | No | Its head branch, which merging deletes unless asked to keep it. |
| `head` | `string` | Yes | The commit its head branch is at, in hex. |
| `may` | `ref` → `#permissions` | Yes |  |
| `method` | `string` | Yes | 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. |
| `queueBlocked` | `string` | No | 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. |
| `queueOnly` | `boolean` | No | 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` | No | 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` | No | 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. |
| `reviewsMissing` | `array` | No | 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` | No | 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` | Yes | 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. |

#### Errors

- **NotFound**: No such repository.
- **AuthenticationRequired**: No one asked: log in to the pages first.

### `dev.knotless.getMergeStatus#note`

**Type**: `object`

A line of text about the pull's reviews.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `text` | `string` | Yes | In plain words. |

### `dev.knotless.getMergeStatus#permissions`

**Type**: `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.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `base` | `boolean` | Yes | Change its target branch: those who may close it. |
| `force` | `boolean` | Yes | Merge it past its checks: the owner alone. |
| `head` | `boolean` | Yes | Change its head branch: its author. |
| `merge` | `boolean` | Yes | Merge it: the owner and collaborators. |
| `queue` | `boolean` | Yes | 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` | Yes | Ask the runners to run its checks again: the owner, in a repository that names runners. |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "conflict": {
      "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"
    },
    "main": {
      "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"
    },
    "note": {
      "description": "A line of text about the pull's reviews.",
      "properties": {
        "text": {
          "description": "In plain words.",
          "type": "string"
        }
      },
      "required": [
        "text"
      ],
      "type": "object"
    },
    "permissions": {
      "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"
    }
  },
  "description": "Whether an open pull can merge now, and what the account asking may do to it.",
  "id": "dev.knotless.getMergeStatus",
  "lexicon": 1
}
```