Organisations

Report a drift run from CI

What one run of the GitHub Action's generate command found in one repository: per source its status, change counts, errors and owners.

POST/orgs/{org}/drift/runs

TL;DR

Question	Answer
What does it do?	Report a drift run from CI.
What does it take?	A JSON body of type `DriftRunBody`.
What does it return?	Status 201 with a body of type `DriftRunReceipt`.
What can go wrong?	`400` the body is not valid; `401` no key, or the key is not valid; `403` not an organisation key (orgs.org_key_required), or the owner's plan does not include the drift dashboard (plan.drift_dashboard_not_included); `404` no such organisation, or the key is another organisation's; `413` the body is larger than 1 mib; `429` too many requests; `503` organisations are not set up on this server. Every failure uses the one error envelope.

What it does

What one run of the GitHub Action's generate command found in one repository: per source its status, change counts, errors and owners. Metadata only, never a file or diagram source. An organisation key only; _ as {org} means the key's own organisation. On a plan with the drift dashboard.

Path parameters

Field	Type	Required	Description
`org`	`string`	yes	The organisation's id or its slug.

Request body

The body has the type DriftRunBody.

Field	Type	Required	Description
`repository`	`string`	yes	The repository the run checked, as owner/name. at most 140 characters; pattern `^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$`.
`ref`	`string \| null`	yes	The git ref the run checked, or null. at least 1 character; at most 255 characters; pattern `^[^\p{Cc}]+$/u`.
`sha`	`string \| null`	yes	The commit the run checked, or null. pattern `^[0-9a-fA-F]{7,64}$`.
`event`	`string \| null`	yes	The event that started the run, or null. at least 1 character; at most 64 characters; pattern `^[a-z][a-z0-9_]*$`.
`runUrl`	`string \| null`	yes	The run on GitHub. An https address of at most 500 characters, or null. at most 500 characters.
`pullRequestUrl`	`string \| null`	yes	The pull request the run opened or checked. An https address of at most 500 characters, or null. at most 500 characters.
`sources`	`DriftSourceBody[]`	yes	Every source the run checked, at most 250. A source of the repository that a run leaves out is removed from the dashboard.
`sources[].name`	`string`	yes	The source's name as the repository's settings write it, 1 to 120 characters. Unique within a run. at least 1 character; at most 120 characters; pattern `^[^\p{Cc}]+$/u`.
`sources[].out`	`string`	yes	The diagram's path in the repository, 1 to 300 characters. at least 1 character; at most 300 characters; pattern `^[^\p{Cc}]+$/u`.
`sources[].status`	`"in-step" \| "drifted" \| "written" \| "failed"`	yes	What the check found: the diagram matches its files (in-step), differs (drifted), was written by the run (written), or could not be made (failed).
`sources[].added`	`integer`	yes	Items in the files that the diagram does not have. minimum 0; maximum 1000000.
`sources[].removed`	`integer`	yes	Items in the diagram that the files no longer have. minimum 0; maximum 1000000.
`sources[].changed`	`integer`	yes	Items both have that differ. minimum 0; maximum 1000000.
`sources[].errors`	`integer`	yes	Errors the run met making this diagram. minimum 0; maximum 1000000.
`sources[].owners`	`string[]`	yes	The owners CODEOWNERS gives the diagram's path, as it writes them: at most 20, each @user, @org/team or an email address.

Responses

Status	Meaning	Body
201	Stored.	`DriftRunReceipt`
400	The body is not valid.	`ErrorResponse`
401	No key, or the key is not valid.	`ErrorResponse`
403	Not an organisation key (orgs.org_key_required), or the owner's plan does not include the drift dashboard (plan.drift_dashboard_not_included).	`ErrorResponse`
404	No such organisation, or the key is another organisation's.	`ErrorResponse`
413	The body is larger than 1 MiB.	`ErrorResponse`
429	Too many requests.	`ErrorResponse`
503	Organisations are not set up on this server.	`ErrorResponse`

Response body

A 201 answer has the type DriftRunReceipt.

Field	Type	Required	Description
`organization`	`object`	yes	The organisation the run was stored for. With `_` in the path, this says which one the key belongs to.
`organization.id`	`string`	yes
`organization.slug`	`string`	yes
`repository`	`string`	yes	The repository, as sent.
`sources`	`integer`	yes	Sources stored. minimum 0.
`drifted`	`integer`	yes	Sources that drifted. minimum 0.
`dashboardUrl`	`string`	yes	The organisation's drift dashboard in the portal, for a signed-in member.

Doc	Why
API reference	Every endpoint, and the error envelope
Schemas	Every request and response type
Tool reference	The operations as callable tools