Organisations
Turn on diagrams in a repository with one pull request
Carries out the plan detect shows: a fresh setup or only the additions to the repository's own setup in one pull request on plotwork/setup, no pull request for a setup that covers everything, nothing for a settings file that does not check; and a trusted publisher for the workflow file the repository uses.
POST
/orgs/{org}/github/repositories/{id}/enableTL;DR
| Question | Answer |
|---|---|
| What does it do? | Turn on diagrams in a repository with one pull request. |
| What does it take? | org, id in the path. |
| What does it return? | Status 200 with a body of type GithubEnable. |
| 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 (github.suspended); 422 nothing in the repository could be drawn (github.nothing_to_draw), or its settings file does not check (github.config_invalid, with the problems in details); 429 too many requests, or GitHub asked to wait (github.rate_limited, with Retry-After); 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. Or the drawing engine is not available (engine.unavailable). Every failure uses the one error envelope. |
What it does
Carries out the plan detect shows: a fresh setup or only the additions to the repository's own setup in one pull request on plotwork/setup, no pull request for a setup that covers everything, nothing for a settings file that does not check; and a trusted publisher for the workflow file the repository uses. Files are never 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 pull request, opened now or open already. | GithubEnable |
| 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 (github.suspended). | ErrorResponse |
| 422 | Nothing in the repository could be drawn (github.nothing_to_draw), or its settings file does not check (github.config_invalid, with the problems in details). | ErrorResponse |
| 429 | Too many requests, or GitHub asked to wait (github.rate_limited, with Retry-After). | 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. Or the drawing engine is not available (engine.unavailable). | ErrorResponse |
Response body
A 200 answer has the type GithubEnable.
| 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 | |
outcome | "opened" | "open" | "complete" | "fix_opened" | yes | opened: a pull request was opened now. open: one was open already. complete: the repository is set up already, so no pull request; only the trusted publisher was registered. fix_opened: its settings file did not check, so a pull request that fixes it was opened, or the open one brought up to date. |
pullRequest | object | null | yes | |
pullRequest.number | integer | yes | |
pullRequest.url | string | yes | |
created | boolean | yes | True when a pull request was opened now. |
trustedPublisher | object | null | yes | The trusted publisher for the workflow, or null when the organisation has twenty already. |
trustedPublisher.id | string | yes | |
trustedPublisher.name | string | yes | |
trustedPublisher.created | boolean | yes | |
keyless | boolean | yes | True when the workflow signs in with no key (id-token: write); false while the pinned Action needs PLOTWORK_API_KEY. |
sources | integer | yes | How many diagrams the pull request adds. |
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 |