Files
mesh-delivery/modules/mesh-delivery-contracts/seats/git/seat.json
T
jschoubben 3f72078853 git seat: a merge call's member may carry the note no delivery
A repository with no watched branch is the forge's business alone: the
seat git's merge-pull merges such a member plainly and starts no delivery.
MemberOutcome and CallMember gain an optional note saying so ("no delivery:
the repository has no watched branch"), why staying the refusal's; the
kept field is what merge-called leaves the member out by. The seat's form
rises to 3; merge-pull's description says it.

Builds: design 47 H2 H-A-471 and its addendum (1)
2026-11-22 13:57:06 +01:00

1877 lines
57 KiB
JSON

{
"format": 1,
"seat": "git",
"scope": "mesh",
"grain": "whole",
"domain": "Delivery",
"decision": "novox/hq ADR 0111",
"description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer.",
"delivers": "git",
"verbs": [
{
"name": "pull",
"description": "One pull request, by its repository and number or by its merge commit: its number, base, head branch, head, merge commit, author and state; for an open one, also what the forge would merge now (merging). A pull request the forge does not hold answers an error naming it.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "its number"
},
"merge-commit": {
"type": "string",
"description": "instead of the number: the merge commit it made"
}
},
"additionalProperties": false,
"required": [
"repository"
]
},
"answer": {
"type": "object",
"properties": {
"pull": {
"$ref": "#/defs/Pull"
},
"merging": {
"$ref": "#/defs/Merging"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what pull answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "branch",
"description": "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"branch": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"repository",
"branch"
]
},
"answer": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"branch": {
"type": "string"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what branch answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "open-pulls",
"description": "Every open pull request of every repository, its head and base, the statuses its base's protection requires and those its head has.",
"input": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"answer": {
"type": "object",
"properties": {
"pulls": {
"type": "array",
"items": {
"$ref": "#/defs/OpenPull"
},
"description": "every open pull request; said empty when none is open, so an answer that lacks it is never read as none"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what open-pulls answers; pulls always said, empty when none is open; error and error-kind beside an empty pulls when it fails",
"required": [
"pulls"
]
},
"class": "read"
},
{
"name": "tags",
"description": "A repository's tags, a page at a time, newest first; the page's bound is said, and more when another page exists.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"prefix": {
"type": "string",
"description": "only tags starting with it"
},
"page": {
"type": "integer",
"description": "the page, from 1"
}
},
"additionalProperties": false,
"required": [
"repository"
]
},
"answer": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"tags": {
"type": "array",
"items": {
"$ref": "#/defs/Tag"
},
"description": "the tags of this page, each with the commit it names (design 47 H2 §796)"
},
"page": {
"type": "integer",
"description": "the page"
},
"bound": {
"type": "integer",
"description": "how many tags a page holds"
},
"more": {
"type": "boolean",
"description": "another page exists"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what tags answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "trees",
"description": "The trees of one commit: the root tree and the tree of every directory that holds a module.json, by their git hashes; with files, every blob under each named directory; with paths, the object of each named path. A listing the forge cut is refused, never answered in part. A directory named in files or paths that the commit does not hold answers the error kind not-found (design 47 H2 §796).",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"paths": {
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "{directory: [path relative to it]}; the root is the empty name"
},
"files": {
"type": "array",
"items": {
"type": "string"
},
"description": "directories whose every blob is answered; the root is the empty name"
}
},
"additionalProperties": false,
"required": [
"repository",
"commit"
]
},
"answer": {
"type": "object",
"properties": {
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"root": {
"type": "string",
"description": "the root tree's hash"
},
"trees": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "directory to its tree's hash, the root as the empty name"
},
"files": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"description": "directory to {path: blob id}"
},
"paths": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"description": "directory to {path: object id}"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what trees answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "file",
"description": "One file at one commit, branch or tag, decoded; a file over 512 KiB is refused. An absent file is answered absent only when the forge said so.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"path": {
"type": "string",
"description": "the file's path from the repository's root",
"minLength": 1
},
"ref": {
"type": "string",
"description": "a commit, branch or tag; the default branch when absent"
}
},
"additionalProperties": false,
"required": [
"repository",
"path"
]
},
"answer": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "the path"
},
"ref": {
"type": "string",
"description": "what was read"
},
"blob": {
"type": "string",
"description": "the file's git blob id"
},
"size": {
"type": "integer",
"description": "its size in bytes"
},
"content": {
"type": "string",
"description": "its content"
},
"absent": {
"type": "boolean",
"description": "the forge holds no such file there"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what file answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "contains",
"description": "Whether one commit contains another: an ancestor of it, or the same.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "the commit asked about",
"minLength": 1
},
"in": {
"type": "string",
"description": "the commit it may be contained in",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"repository",
"commit",
"in"
]
},
"answer": {
"type": "object",
"properties": {
"commit": {
"type": "string",
"description": "the commit"
},
"in": {
"type": "string",
"description": "the other"
},
"contains": {
"type": "boolean",
"description": "in contains commit"
},
"ahead": {
"type": "integer",
"description": "how many commits commit is ahead of in"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what contains answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "statuses",
"description": "The statuses a commit carries, the newest of each context.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"commit"
]
},
"answer": {
"type": "object",
"properties": {
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"combined": {
"type": "string",
"description": "the forge's combined state"
},
"statuses": {
"type": "array",
"items": {
"$ref": "#/defs/Status"
},
"description": "the newest of each context"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what statuses answers; error and error-kind alone when it fails"
},
"class": "read"
},
{
"name": "status",
"description": "Set a commit status. An act: its id is the caller's, and the same id said again sets it again to the same.",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"context": {
"type": "string",
"description": "the context, such as mesh/check",
"minLength": 1
},
"state": {
"type": "string",
"description": "the state",
"enum": [
"pending",
"success",
"failure",
"error",
"warning"
]
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"commit",
"context",
"state"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what status answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "comment",
"description": "Add a comment to a pull request. The comment carries the act's id, and an id the pull request already holds is skipped (held).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"text": {
"type": "string",
"description": "the comment, markdown",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"text"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what comment answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "view",
"description": "Keep the delivery's one view comment on a pull request: made the first time, edited in place after; it carries the act's id, and an id already held is skipped (held).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"text": {
"type": "string",
"description": "the view, markdown",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"number",
"text"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what view answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "note",
"description": "Append one line to a commit's note under refs/notes/mesh-plan. The line carries the act's id, and an id the note already holds is skipped (held).",
"input": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id",
"minLength": 1
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"line": {
"type": "string",
"description": "the line, one line",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"id",
"repository",
"commit",
"line"
]
},
"answer": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "the act's id, as the caller gave it"
},
"performed": {
"type": "boolean",
"description": "the forge holds the act now"
},
"held": {
"type": "boolean",
"description": "the id was already held on the pull request or the note, so nothing was done again"
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what note answers; error and error-kind alone when it fails"
},
"class": "act"
},
{
"name": "merge-pull",
"description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H §734, §735, §766; ADR 0682 §1, §2). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. A member whose repository has no watched branch is judged against nothing of the module graph and merged plainly in the order named, starting no delivery: its outcome says merged with the note no delivery (H-A-471). When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.",
"input": {
"type": "object",
"properties": {
"pulls": {
"type": "array",
"minItems": 1,
"description": "the members, in the order they are merged",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"head": {
"type": "string",
"description": "the head the caller names",
"pattern": "^[0-9a-f]{40}$"
}
},
"additionalProperties": false,
"required": [
"repository",
"number",
"head"
]
}
},
"by": {
"type": "string",
"description": "the caller as who@node, recorded beside the bus account the tool runner proves",
"minLength": 1
}
},
"additionalProperties": false,
"required": [
"pulls",
"by"
]
},
"answer": {
"type": "object",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"members": {
"type": "array",
"description": "each member's outcome, in the order named",
"items": {
"$ref": "#/defs/MemberOutcome"
}
},
"error": {
"type": "string",
"description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what merge-pull answers at the call's end; error and error-kind alone when it fails"
},
"class": "act",
"timeout": 120
},
{
"name": "tag",
"class": "act",
"description": "Write the git tag of a released version, <directory>/vMAJOR.MINOR.PATCH for a Go package (design 47 H2 §796), at the commit its build was made from; the builder writes it only on the catalog's version-released (design 47 G section 370). A tag already at that commit is answered performed. An error answer carries error and error-kind.",
"input": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>"
},
"tag": {
"type": "string",
"description": "the tag"
},
"commit": {
"type": "string",
"description": "the commit it is written at"
}
},
"additionalProperties": false,
"required": [
"repository",
"tag",
"commit"
]
},
"answer": {
"type": "object",
"properties": {
"tag": {
"type": "string",
"description": "the tag, as asked"
},
"performed": {
"type": "boolean",
"description": "the forge holds the tag at that commit now"
},
"error": {
"type": "string",
"description": "why the forge could not write it: set alone with error-kind"
},
"error-kind": {
"$ref": "#/defs/ErrorKind"
},
"part": {
"type": "string",
"description": "with the error kind away, what did not answer (design 47 H2 §776)"
},
"words": {
"type": "string",
"description": "with the error kind away, the holder's words (design 47 H2 §776)"
}
},
"description": "what tag answers; error and error-kind alone when it fails"
}
}
],
"events": [
{
"name": "pull-updated",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it"
},
"url": {
"type": "string",
"description": "its page"
},
"base-head": {
"type": "string",
"description": "the base branch's head as the head was announced; absent when it could not be read"
},
"change": {
"$ref": "#/defs/Change"
}
},
"description": "a pull request's new head, announced once per head and trunk commit",
"required": [
"repository",
"number",
"branch",
"head",
"base"
]
}
},
{
"name": "pull-merged",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it"
},
"url": {
"type": "string",
"description": "its page"
},
"merge-commit": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"merged-at": {
"type": "string",
"description": "when",
"format": "date-time"
},
"change": {
"$ref": "#/defs/Change"
},
"head-checks": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "the head's statuses by context, their states; absent when they could not be read"
}
},
"description": "a pull request merged, announced once by its merge commit",
"required": [
"repository",
"number",
"branch",
"head",
"base",
"merge-commit"
]
}
},
{
"name": "pull-closed",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it"
},
"url": {
"type": "string",
"description": "its page"
}
},
"description": "a pull request closed without a merge, announced once by its head",
"required": [
"repository",
"number",
"branch",
"head",
"base"
]
}
},
{
"name": "forge-pull",
"body": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "what the forge said: opened, reopened, synchronized, edited, closed, merged"
},
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "its number"
},
"branch": {
"type": "string",
"description": "its head branch"
},
"head": {
"type": "string",
"description": "its head commit"
},
"base": {
"type": "string",
"description": "its base branch"
},
"author": {
"type": "string",
"description": "who opened it"
},
"merged": {
"type": "boolean",
"description": "merged"
},
"merge-commit": {
"type": "string",
"description": "the merge commit"
},
"sender": {
"type": "string",
"description": "who acted"
}
},
"description": "the forge's own webhook of a pull request, trimmed; never its description",
"required": [
"action",
"repository",
"number"
]
}
},
{
"name": "forge-status",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"commit": {
"type": "string",
"description": "the commit"
},
"context": {
"type": "string",
"description": "the context"
},
"state": {
"type": "string",
"description": "the state"
},
"description": {
"type": "string",
"description": "what it says"
},
"sender": {
"type": "string",
"description": "who set it"
}
},
"description": "the forge's own webhook of a commit status",
"required": [
"repository",
"commit",
"context",
"state"
]
}
},
{
"name": "forge-delete",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"ref": {
"type": "string",
"description": "the deleted branch or tag"
},
"ref-type": {
"type": "string",
"description": "branch or tag"
},
"sender": {
"type": "string",
"description": "who deleted it"
}
},
"description": "the forge's own webhook of a deleted branch or tag",
"required": [
"repository",
"ref"
]
}
},
{
"name": "repo-writable",
"body": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"account": {
"type": "string",
"description": "the account that writes it now"
}
},
"description": "a repository the forge's account can write again",
"required": [
"repository",
"account"
]
}
},
{
"name": "branch-moved",
"body": {
"type": "object",
"description": "a branch's new head, by a merge or an admitted push, from the forge's push webhook (design 47 lines 507-512): its hearer takes the head from the forge's own record by the verb branch, never from this body",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"branch": {
"type": "string",
"minLength": 1
},
"head": {
"type": "string",
"description": "the head the webhook said, a commit's full 40-hex sha; read again by branch",
"pattern": "^[0-9a-f]{40}$"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"repository",
"branch"
]
},
"keep": {
"max-age-days": 90,
"max-mib": 64
}
},
{
"name": "merge-called",
"subject": "merge-called.<call>",
"body": {
"$ref": "#/bodies/MergeCalled"
},
"keep": {
"max-age-days": 30,
"max-mib": 64
}
}
],
"family": {
"name": "git.events",
"max-age-days": 7
},
"states": [
{
"name": "failed-steps",
"template": "state",
"history": 1,
"description": "each failed required step by module and build-input fingerprint, heard from the runner's step-ended; an entry is deleted once none of its commits is a watched branch's head or the head an open pull request names (design 47 *The runner's kept data*)",
"key-forms": [
{
"key": "<module>.<fingerprint>.<step>",
"value": {
"$ref": "#/defs/FailedStep"
},
"description": "a failed required step"
}
]
},
{
"name": "calls",
"template": "state",
"history": 1,
"description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H §766, H-A-47)",
"key-forms": [
{
"key": "call.<call>",
"value": {
"$ref": "#/defs/Call"
},
"description": "one merge call"
}
]
}
],
"defs": {
"Pull": {
"type": "object",
"properties": {
"repository": {
"type": "string",
"description": "the repository, <owner>/<name>",
"minLength": 1
},
"number": {
"type": "integer",
"description": "the pull request's number"
},
"title": {
"type": "string",
"description": "its title"
},
"author": {
"type": "string",
"description": "who opened it, the forge's login"
},
"branch": {
"type": "string",
"description": "its head branch: what a delivery group is named by"
},
"head": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"base": {
"type": "string",
"description": "the branch it merges into"
},
"state": {
"type": "string",
"description": "open, merged or closed",
"enum": [
"open",
"merged",
"closed"
]
},
"merge-commit": {
"type": "string",
"description": "the merge commit, once merged"
},
"merged-at": {
"type": "string",
"description": "when it merged",
"format": "date-time"
},
"url": {
"type": "string",
"description": "its page on the forge"
}
},
"description": "one pull request as the forge holds it; never its description (ADR 0659 §1)",
"required": [
"repository",
"number",
"branch",
"head",
"base",
"state"
]
},
"Merging": {
"type": "object",
"properties": {
"mergeable": {
"type": "boolean",
"description": "the forge's own word on whether it merges into its base now: false while it is in conflict with its base, or while the forge works that out after the base moved"
},
"protected": {
"type": "boolean",
"description": "whether a protection rule guards its base branch"
},
"required": {
"type": "array",
"items": {
"type": "string"
},
"description": "the status contexts the base branch's protection requires; none when it requires none"
},
"writes": {
"type": "boolean",
"description": "whether the forge's merging account may write the repository: false, its statuses and its merge are refused"
}
},
"description": "what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 §1): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one",
"required": [
"mergeable",
"protected",
"required",
"writes"
]
},
"Status": {
"type": "object",
"properties": {
"context": {
"type": "string",
"description": "the status's context, such as mesh/check"
},
"state": {
"type": "string",
"description": "pending, success, failure, error or warning"
},
"description": {
"type": "string",
"description": "what it says"
},
"target": {
"type": "string",
"description": "the page it links to"
},
"at": {
"type": "string",
"description": "when it was set",
"format": "date-time"
},
"by": {
"type": "string",
"description": "who set it"
}
},
"description": "the newest status of one context on a commit",
"required": [
"context",
"state"
]
},
"OpenPull": {
"type": "object",
"properties": {
"pull": {
"$ref": "#/defs/Pull"
},
"required": {
"type": "array",
"items": {
"type": "string"
},
"description": "the contexts the base branch's protection requires; none when it requires none"
},
"checks": {
"type": "object",
"additionalProperties": {
"$ref": "#/defs/Status"
},
"description": "the head's statuses by context, the newest of each"
}
},
"description": "an open pull request, with the statuses its base requires and those its head has",
"required": [
"pull",
"required",
"checks"
]
},
"Change": {
"type": "object",
"properties": {
"paths": {
"type": "array",
"items": {
"type": "string"
},
"description": "the paths it changed"
},
"paths-truncated": {
"type": "boolean",
"description": "the forge cut the list"
},
"removed": {
"type": "array",
"items": {
"type": "string"
},
"description": "which of them it deleted"
},
"module-dirs": {
"type": "array",
"items": {
"type": "string"
},
"description": "the changed directories that hold a module at its head; absent when they could not be read"
}
},
"description": "what a pull request changed",
"required": [
"paths"
]
},
"ErrorKind": {
"type": "string",
"enum": [
"refused",
"not-found",
"failed",
"away"
],
"description": "which kind of error, set with error alone: refused, the forge or the holder refused and error says why in the forge's own words; not-found, the forge said that what was asked about (a repository, a commit, a pull request, a branch or a tag) does not exist, so a caller never reads it out of error's words; failed, the forge failed or could not be reached, so the act or read could not be performed; away, a part the holder depends on (the forge, its store) is away, with part naming what did not answer and words: a caller reads it as a transport fault and calls again (design 47 H2 §776)"
},
"FailedStep": {
"type": "object",
"description": "a failed required step at a build-input fingerprint, with the commits it was seen at and the run that failed it (design 47 *Judged from its own state, never by a call*); cleared by a later passing rerun of that step whose proved caller is the operator or a healer",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"module": {
"type": "string"
},
"fingerprint": {
"type": "string",
"description": "the build-input fingerprint the step failed at"
},
"step": {
"type": "string"
},
"artifact": {
"type": "string",
"description": "the artifact reference, <module>:<artifact>"
},
"run": {
"type": "string",
"description": "the run that failed it: the runner's pipeline key"
},
"commits": {
"type": "array",
"items": {
"type": "string",
"description": "a commit, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
},
"description": "every commit it was seen at"
},
"said": {
"type": "string",
"description": "why it failed, as the runner's step-ended said"
},
"at": {
"type": "string",
"format": "date-time"
}
},
"required": [
"module",
"fingerprint",
"step",
"run",
"commits"
]
},
"MemberOutcome": {
"type": "object",
"description": "one member of a merge call and where it stands (design 47 H §766, H-A-22)",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
],
"description": "judged, judged and not merged; merged, with its commit; refused, with why"
},
"commit": {
"type": "string",
"description": "for merged, the merge commit; for a member refused already-merged, its commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why, naming the step for a failed required step"
},
"note": {
"type": "string",
"description": "for a member merged plainly, its repository having no watched branch: \"no delivery: the repository has no watched branch\"; it starts no delivery and merge-called leaves it out (design 47 H2 H-A-471)"
}
},
"required": [
"repository",
"number",
"state"
]
},
"Call": {
"type": "object",
"description": "one merge call, written before its first merge and updated as each member merges (design 47 H §766)",
"properties": {
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved for the call"
},
"at": {
"type": "string",
"format": "date-time"
},
"members": {
"type": "array",
"items": {
"$ref": "#/defs/CallMember"
}
},
"said": {
"type": "boolean",
"description": "merge-called was said for it"
}
},
"required": [
"by",
"account",
"at",
"members",
"said"
]
},
"CallMember": {
"type": "object",
"description": "one member of a kept call",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, read at judging: a watched branch, but for a member noted as of a repository with no watched branch"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"state": {
"type": "string",
"enum": [
"judged",
"merged",
"refused"
]
},
"commit": {
"type": "string",
"description": "for merged, the merge commit",
"pattern": "^[0-9a-f]{40}$"
},
"why": {
"type": "string",
"description": "for refused, why"
},
"note": {
"type": "string",
"description": "for a member merged plainly, its repository having no watched branch: \"no delivery: the repository has no watched branch\"; it starts no delivery and merge-called leaves it out (design 47 H2 H-A-471)"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"state"
]
},
"Tag": {
"type": "object",
"description": "a tag and the commit it names (design 47 H2 §796)",
"properties": {
"tag": {
"type": "string"
},
"commit": {
"type": "string",
"description": "the commit it names, its full 40-hex sha",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"tag",
"commit"
]
}
},
"bodies": {
"MergeCalled": {
"type": "object",
"description": "a merge call's members merged or refused, said once by the forge module (design 47 H §736, §767)",
"properties": {
"call": {
"type": "string",
"description": "the merge call, 16 lowercase hex characters made once per call",
"pattern": "^[0-9a-f]{16}$"
},
"by": {
"type": "string",
"description": "the caller as who@node"
},
"account": {
"type": "string",
"description": "the bus account the tool runner proved"
},
"at": {
"type": "string",
"format": "date-time",
"description": "the time of the last merge"
},
"members": {
"type": "array",
"description": "one per landed member",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"branch": {
"type": "string",
"description": "the pull request's base, a watched branch"
},
"head": {
"type": "string",
"pattern": "^[0-9a-f]{40}$"
},
"commit": {
"type": "string",
"description": "the merge commit the forge records for the pull request",
"pattern": "^[0-9a-f]{40}$"
}
},
"required": [
"repository",
"number",
"branch",
"head",
"commit"
]
}
},
"refused": {
"type": "array",
"description": "one per member not merged after every member was judged (design 47 H §767)",
"items": {
"type": "object",
"properties": {
"repository": {
"type": "string"
},
"number": {
"type": "integer"
},
"why": {
"type": "string"
}
},
"required": [
"repository",
"number",
"why"
]
}
}
},
"required": [
"call",
"by",
"account",
"at",
"members"
]
}
},
"form": 3
}