Organisations
Scan a repository for formats Plotwork draws from
Reads the default branch's tree, paths only, and answers the sources a settings file would name.
POST
/orgs/{org}/github/repositories/{id}/detectTL;DR
| Question | Answer |
|---|---|
| What does it do? | Scan a repository for formats Plotwork draws from. |
| What does it take? | org, id in the path. |
| What does it return? | Status 200 with a body of type GithubDetect. |
| What can go wrong? | 401 not signed in; 403 a member may not (orgs.forbidden), the plan has no GitHub App (plan.github_app_not_included), or the request came from an origin that may not make changes; 404 no such organisation or repository (github.repository_not_found); 409 the installation is suspended on GitHub (github.suspended); 422 the repository is empty (github.nothing_to_draw); 429 too many requests, or GitHub asked to wait (github.rate_limited); 502 GitHub could not be reached (github.unavailable); 503 the GitHub App is not set up on this server (github.not_configured), or organisations are not. Every failure uses the one error envelope. |
What it does
Reads the default branch's tree, paths only, and answers the sources a settings file would name. Only the format names are stored. The owner and an admin, on Pro and Enterprise.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
id | string | yes | GitHub's id. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The sources found. | GithubDetect |
| 401 | Not signed in. | ErrorResponse |
| 403 | A member may not (orgs.forbidden), the plan has no GitHub App (plan.github_app_not_included), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation or repository (github.repository_not_found). | ErrorResponse |
| 409 | The installation is suspended on GitHub (github.suspended). | ErrorResponse |
| 422 | The repository is empty (github.nothing_to_draw). | ErrorResponse |
| 429 | Too many requests, or GitHub asked to wait (github.rate_limited). | ErrorResponse |
| 502 | GitHub could not be reached (github.unavailable). | ErrorResponse |
| 503 | The GitHub App is not set up on this server (github.not_configured), or organisations are not. | ErrorResponse |
Response body
A 200 answer has the type GithubDetect.
| Field | Type | Required | Description |
|---|---|---|---|
repository | GithubRepository | yes | |
repository.id | string | yes | GitHub's repository id. |
repository.installationId | string | yes | |
repository.fullName | string | yes | |
repository.private | boolean | yes | |
repository.defaultBranch | string | yes | |
repository.formats | array | null | yes | The import formats the last scan found, such as terraform; null before a scan and after a push to the default branch. |
repository.detectedAt | integer | null | yes | |
repository.status | "none" | "pr_open" | "fix_open" | "merged" | "closed" | "adopted" | "reporting" | "failing" | yes | none: not enabled. pr_open: the setup pull request is open. fix_open: a pull request that fixes the settings file is open; once it closes, the repository is scanned again. merged: merged, no drift run since. adopted: set up already, so Enable registered CI with no pull request, and no drift run since. reporting or failing: the latest drift run since it was enabled was clean, or drifted or failed. closed: the pull request was closed without merging. |
repository.pullRequest | object | null | yes | |
repository.pullRequest.number | integer | yes | |
repository.pullRequest.url | string | yes | |
repository.enabledAt | integer | null | yes | |
repository.lastRun | object | null | yes | The repository's latest drift run, whenever it was sent. |
repository.lastRun.checkedAt | integer | yes | |
repository.lastRun.drifted | integer | yes | |
repository.lastRun.failed | integer | yes | |
sources | object[] | yes | The sources a settings file would name, with their paths. Only the format names are stored. |
sources[].name | string | yes | |
sources[].format | string | yes | |
sources[].from | string[] | yes | |
sources[].out | string | yes | |
truncated | boolean | yes | True when the tree was too large to read whole, so only part of it was scanned. |
plan | GithubPlan | yes | |
plan.outcome | "setup" | "additions" | "complete" | "invalid" | "nothing" | yes | setup: no settings file yet, so a pull request adds one, the workflow and the diagrams. additions: the repository uses Plotwork, and a pull request adds only what it lacks. complete: it covers everything found, so only CI is registered. invalid: its settings file does not check and is left alone. nothing: nothing to draw. |
plan.summary | string | yes | What happens, in one sentence. |
plan.added | object[] | yes | |
plan.added[].name | string | yes | |
plan.added[].format | string | yes | |
plan.added[].from | string[] | yes | |
plan.added[].out | string | yes | |
plan.kept | string[] | yes | The sources the settings file has, every one left as it is. |
plan.workflow | object | null | yes | The workflow written, edited in place (report-drift and id-token: write added), or left as it is. |
plan.workflow.action | "add" | "edit" | "keep" | yes | |
plan.workflow.file | string | yes | |
plan.suggestions | string[] | yes | What the workflow still lacks and was not changed, such as an older pin of the Action. |
plan.problems | object[] | yes | For invalid: where the settings file does not check, each with a hint. |
plan.problems[].code | string | yes | |
plan.problems[].message | string | yes | |
plan.problems[].line | integer | yes | |
plan.problems[].column | integer | yes | |
plan.problems[].hint | string | null | yes | |
plan.repair | object | null | yes | For invalid: the repair Enable would make. |
plan.repair.fixable | boolean | yes | True when every problem has a plain fix, so Enable opens a pull request that fixes the file. |
plan.repair.fixes | object[] | yes | |
plan.repair.needsYou | string[] | yes | What the fix leaves as it is for the person: a source that reads no file, a key or value with no plain match. |
plan.followUp | string | null | yes | For a fixable invalid: what Enable does once the fix is merged. |
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 |