# dev.knotless.check

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

✓ This is the authoritative definition for this NSID.

## Description

What a workflow did at a commit a ref pointed at, or at the head of a pull, as the runner that ran it reports.

## Links

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

## Definitions

### `dev.knotless.check#batched`

**Type**: `object`

A pull in a merge queue's batch, as the run squashed it.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `commit` | `string` | Yes | The hex object ID of the pull's own commit in the batch. |
| `head` | `string` | No | The hex object ID of the pull's head that was squashed. |
| `pull` | `string` (at-uri) | Yes | The dev.knotless.pull record. |

### `dev.knotless.check#image`

**Type**: `object`

A picture a run made, as an output.

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `alt` | `string` | Yes | What the picture shows, from its file's name, for whoever reads it without seeing it: a person or an agent. |
| `image` | `blob` | Yes |  |

### `dev.knotless.check`

**Type**: `record`

Kept in the runner's account, keyed `<owner hash>.<repo key>.<ref hash>.<commit>.<workflow>`, where each hash is the first 26 characters of the lowercase unpadded base32 SHA-256 of the owner's DID or the full ref name (for a pull's run, the pull's AT-URI), so each commit keeps its own check of each workflow, replaced only when that commit runs again. A pull's run is keyed `<owner hash>.<repo key>.<pull hash>.<commit>.<baseCommit>.<workflow>`, so a run against a newer base is a check of its own. A runner may delete checks of no more use: a batch's, a closed pull's, ones superseded by a newer run of the same workflow, and the default branch's after a while. Readers trust only a runner the repository names.

**Key**: `any`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `baseCommit` | `string` | No | For a pull's run, the hex object ID of the tip of the branch the pull is into that its head was merged with: the run is of that merge, as merging the pull would make it, so it is current only while both the head and the base are where they were. |
| `batch` | `array` | No | For a run of a merge queue's batch (dev.knotless.queue): the pulls it would land, in order, each squashed as a commit of its own onto `baseCommit`, the tip of the branch `ref` names, and `commit` the last of them. Once every run of the batch passes, the branch moves to `commit`. |
| `commit` | `string` | Yes | The hex object ID the ref pointed at. |
| `error` | `string` | No | Why the workflow did not run: for `error`, or for a `failure` of a pull that does not merge, the paths that conflict. |
| `finishedAt` | `string` (datetime) | No |  |
| `generation` | `integer` | No | The ref's generation at that commit. |
| `log` | `blob` | No | Every step's output, interleaved as it was written; the tail, when there was more. |
| `outputs` | `array` | No | What the run made to be looked at, such as screenshots of the pages a change moved, in the order of their names. Kinds unknown to a reader are passed over. |
| `pull` | `string` (at-uri) | No | The dev.knotless.pull record, for a run of the pull's head. |
| `queue` | `string` | No | For a pull's run, where its workflow runs in the merge queue, when not only on each batch: `first`, as the workflow's `queue: first` asks, is a pre-flight, which a queued pull must pass at its head before it goes into a batch. |
| `ref` | `string` | Yes | The full ref name the run was for, such as refs/heads/main; for a pull's run, its head branch in the repository the pull brings it from. |
| `repo` | `ref` → `dev.knotless.defs#repoRef` | Yes | The repository whose ref moved, or the target of the pull. |
| `skipped` | `string` | No | For a `success` that ran no step: why, as people read it, such as the paths its workflow names, none of which the change touched. Its steps are then each `skipped`. |
| `startedAt` | `string` (datetime) | Yes |  |
| `status` | `string` | Yes | `queued` is a run filed and waiting for a job on its runner, no step started yet: it is filed `running` once it starts, its `startedAt` then. `failure` is a step that exited non-zero or ran out of time, or a pull's head that conflicts with its base; `error` is the runner failing to run the workflow at all; `cancelled` is a run stopped for a newer commit's run of the workflow on the same ref or pull. A `success` with `skipped` ran no step, as the change touched none of the paths the workflow names, and passes as any `success` does. |
| `steps` | `array` | No | Each step the workflow has, in order. Absent for `error`. |
| `workflow` | `string` | Yes | The workflow's name, which is also the last part of the record key. |

### `dev.knotless.check#step`

**Type**: `object`

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `durationMs` | `integer` | No | How long the step ran, in milliseconds. |
| `exitCode` | `integer` | No | Absent when the step was killed for running out of time. |
| `name` | `string` | Yes | The step's name in the workflow, or `step <n>` for one with none. |
| `status` | `string` | Yes | `cancelled` is the step running when its run was cancelled. |

## Raw Schema

```json
{
  "$type": "com.atproto.lexicon.schema",
  "defs": {
    "batched": {
      "description": "A pull in a merge queue's batch, as the run squashed it.",
      "properties": {
        "commit": {
          "description": "The hex object ID of the pull's own commit in the batch.",
          "maxLength": 64,
          "minLength": 40,
          "type": "string"
        },
        "head": {
          "description": "The hex object ID of the pull's head that was squashed.",
          "maxLength": 64,
          "minLength": 40,
          "type": "string"
        },
        "pull": {
          "description": "The dev.knotless.pull record.",
          "format": "at-uri",
          "type": "string"
        }
      },
      "required": [
        "pull",
        "commit"
      ],
      "type": "object"
    },
    "image": {
      "description": "A picture a run made, as an output.",
      "properties": {
        "alt": {
          "description": "What the picture shows, from its file's name, for whoever reads it without seeing it: a person or an agent.",
          "maxGraphemes": 300,
          "maxLength": 3000,
          "type": "string"
        },
        "image": {
          "accept": [
            "image/png",
            "image/jpeg",
            "image/webp",
            "image/gif"
          ],
          "maxSize": 1000000,
          "type": "blob"
        }
      },
      "required": [
        "image",
        "alt"
      ],
      "type": "object"
    },
    "main": {
      "description": "Kept in the runner's account, keyed `<owner hash>.<repo key>.<ref hash>.<commit>.<workflow>`, where each hash is the first 26 characters of the lowercase unpadded base32 SHA-256 of the owner's DID or the full ref name (for a pull's run, the pull's AT-URI), so each commit keeps its own check of each workflow, replaced only when that commit runs again. A pull's run is keyed `<owner hash>.<repo key>.<pull hash>.<commit>.<baseCommit>.<workflow>`, so a run against a newer base is a check of its own. A runner may delete checks of no more use: a batch's, a closed pull's, ones superseded by a newer run of the same workflow, and the default branch's after a while. Readers trust only a runner the repository names.",
      "key": "any",
      "record": {
        "properties": {
          "baseCommit": {
            "description": "For a pull's run, the hex object ID of the tip of the branch the pull is into that its head was merged with: the run is of that merge, as merging the pull would make it, so it is current only while both the head and the base are where they were.",
            "maxLength": 64,
            "minLength": 40,
            "type": "string"
          },
          "batch": {
            "description": "For a run of a merge queue's batch (dev.knotless.queue): the pulls it would land, in order, each squashed as a commit of its own onto `baseCommit`, the tip of the branch `ref` names, and `commit` the last of them. Once every run of the batch passes, the branch moves to `commit`.",
            "items": {
              "ref": "#batched",
              "type": "ref"
            },
            "maxLength": 64,
            "type": "array"
          },
          "commit": {
            "description": "The hex object ID the ref pointed at.",
            "maxLength": 64,
            "minLength": 40,
            "type": "string"
          },
          "error": {
            "description": "Why the workflow did not run: for `error`, or for a `failure` of a pull that does not merge, the paths that conflict.",
            "maxLength": 4096,
            "type": "string"
          },
          "finishedAt": {
            "format": "datetime",
            "type": "string"
          },
          "generation": {
            "description": "The ref's generation at that commit.",
            "minimum": 1,
            "type": "integer"
          },
          "log": {
            "accept": [
              "text/plain"
            ],
            "description": "Every step's output, interleaved as it was written; the tail, when there was more.",
            "maxSize": 1000000,
            "type": "blob"
          },
          "outputs": {
            "description": "What the run made to be looked at, such as screenshots of the pages a change moved, in the order of their names. Kinds unknown to a reader are passed over.",
            "items": {
              "refs": [
                "#image"
              ],
              "type": "union"
            },
            "maxLength": 32,
            "type": "array"
          },
          "pull": {
            "description": "The dev.knotless.pull record, for a run of the pull's head.",
            "format": "at-uri",
            "type": "string"
          },
          "queue": {
            "description": "For a pull's run, where its workflow runs in the merge queue, when not only on each batch: `first`, as the workflow's `queue: first` asks, is a pre-flight, which a queued pull must pass at its head before it goes into a batch.",
            "knownValues": [
              "first"
            ],
            "maxLength": 64,
            "type": "string"
          },
          "ref": {
            "description": "The full ref name the run was for, such as refs/heads/main; for a pull's run, its head branch in the repository the pull brings it from.",
            "maxLength": 1024,
            "type": "string"
          },
          "repo": {
            "description": "The repository whose ref moved, or the target of the pull.",
            "ref": "dev.knotless.defs#repoRef",
            "type": "ref"
          },
          "skipped": {
            "description": "For a `success` that ran no step: why, as people read it, such as the paths its workflow names, none of which the change touched. Its steps are then each `skipped`.",
            "maxGraphemes": 1000,
            "maxLength": 4000,
            "type": "string"
          },
          "startedAt": {
            "format": "datetime",
            "type": "string"
          },
          "status": {
            "description": "`queued` is a run filed and waiting for a job on its runner, no step started yet: it is filed `running` once it starts, its `startedAt` then. `failure` is a step that exited non-zero or ran out of time, or a pull's head that conflicts with its base; `error` is the runner failing to run the workflow at all; `cancelled` is a run stopped for a newer commit's run of the workflow on the same ref or pull. A `success` with `skipped` ran no step, as the change touched none of the paths the workflow names, and passes as any `success` does.",
            "knownValues": [
              "queued",
              "running",
              "success",
              "failure",
              "error",
              "cancelled"
            ],
            "maxLength": 64,
            "type": "string"
          },
          "steps": {
            "description": "Each step the workflow has, in order. Absent for `error`.",
            "items": {
              "ref": "#step",
              "type": "ref"
            },
            "maxLength": 256,
            "type": "array"
          },
          "workflow": {
            "description": "The workflow's name, which is also the last part of the record key.",
            "maxLength": 64,
            "type": "string"
          }
        },
        "required": [
          "repo",
          "ref",
          "commit",
          "workflow",
          "status",
          "startedAt"
        ],
        "type": "object"
      },
      "type": "record"
    },
    "step": {
      "properties": {
        "durationMs": {
          "description": "How long the step ran, in milliseconds.",
          "minimum": 0,
          "type": "integer"
        },
        "exitCode": {
          "description": "Absent when the step was killed for running out of time.",
          "type": "integer"
        },
        "name": {
          "description": "The step's name in the workflow, or `step <n>` for one with none.",
          "maxLength": 256,
          "type": "string"
        },
        "status": {
          "description": "`cancelled` is the step running when its run was cancelled.",
          "knownValues": [
            "success",
            "failure",
            "skipped",
            "cancelled"
          ],
          "maxLength": 64,
          "type": "string"
        }
      },
      "required": [
        "name",
        "status"
      ],
      "type": "object"
    }
  },
  "description": "What a workflow did at a commit a ref pointed at, or at the head of a pull, as the runner that ran it reports.",
  "id": "dev.knotless.check",
  "lexicon": 1
}
```