Organisations
Make a hand-drawn diagram verifiable
Opens a GitHub App pull request that adds the matching source to the repository's settings with its generated diagram, so CI checks it from then on.
POST
/orgs/{org}/evidence/findings/{id}/verifyTL;DR
| Question | Answer |
|---|---|
| What does it do? | Make a hand-drawn diagram verifiable. |
| What does it take? | org, id in the path. |
| What does it return? | Status 200 with a body of type EvidenceVerify. |
| What can go wrong? | 401 not signed in; 403 a member or a reader (orgs.forbidden), a plan without compliance evidence (plan.compliance_evidence_not_included), or an origin that may not make changes; 404 no such finding (evidence.finding_not_found) or repository (github.repository_not_found); 409 the repository is not set up (evidence.not_set_up), or the installation is suspended (github.suspended); 422 no source to draw it from (evidence.nothing_to_verify); 429 too many requests, or GitHub asked to wait (github.rate_limited); 502 GitHub did not answer as expected (github.unavailable); 503 the GitHub App or the Engine is not set up here. Every failure uses the one error envelope. |
What it does
Opens a GitHub App pull request that adds the matching source to the repository's settings with its generated diagram, so CI checks it from then on. The Markdown is left as it is. The owner and admins, on Enterprise. Audited.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
id | string | yes |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | What was done. | EvidenceVerify |
| 401 | Not signed in. | ErrorResponse |
| 403 | A member or a reader (orgs.forbidden), a plan without compliance evidence (plan.compliance_evidence_not_included), or an origin that may not make changes. | ErrorResponse |
| 404 | No such finding (evidence.finding_not_found) or repository (github.repository_not_found). | ErrorResponse |
| 409 | The repository is not set up (evidence.not_set_up), or the installation is suspended (github.suspended). | ErrorResponse |
| 422 | No source to draw it from (evidence.nothing_to_verify). | ErrorResponse |
| 429 | Too many requests, or GitHub asked to wait (github.rate_limited). | ErrorResponse |
| 502 | GitHub did not answer as expected (github.unavailable). | ErrorResponse |
| 503 | The GitHub App or the Engine is not set up here. | ErrorResponse |
Response body
A 200 answer has the type EvidenceVerify.
| Field | Type | Required | Description |
|---|---|---|---|
outcome | "opened" | "present" | yes | opened: a pull request; present: the settings already draw the source. |
source | object | yes | |
source.name | string | yes | |
source.format | string | yes | |
pullRequest | object | null | yes | |
pullRequest.number | integer | yes | |
pullRequest.url | string | yes |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |