Organisations
Add a trusted publisher
Trusts one GitHub Actions workflow of one repository to act for the organisation with no API key, by the ID token GitHub gives each job, exchanged at POST /oidc/token.
POST
/orgs/{org}/trusted-publishersTL;DR
| Question | Answer |
|---|---|
| What does it do? | Add a trusted publisher. |
| What does it take? | A JSON body of type TrustedPublisherBody. |
| What does it return? | Status 201 with a body of type TrustedPublisher. |
| What can go wrong? | 400 the body is not valid; 401 not signed in; 403 a member may not (orgs.forbidden), the plan has no trusted publishers (plan.trusted_publishers_not_included), or the request came from an origin that may not make changes; 404 no such organisation, or the caller is not a member of it; 409 the organisation already trusts that run (trusted_publishers.duplicate), or has twenty (trusted_publishers.limit_reached); 422 GitHub has no such account, or names the repository another (trusted_publishers.invalid); 429 too many requests; 503 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
Trusts one GitHub Actions workflow of one repository to act for the organisation with no API key, by the ID token GitHub gives each job, exchanged at POST /oidc/token. environment and ref narrow it; permissions is diagrams, drift:write or both. GitHub's ids for the repository and its owner are pinned. At most twenty. 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. |
Request body
The body has the type TrustedPublisherBody.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | A name to recognise it by in the usage, the call history and the audit log. Left out or blank, the repository name and the workflow. at most 60 characters. |
provider | "github" | no | The CI provider. github, the default, is the only one. |
repository | string | yes | The repository, owner/name. at most 140 characters. |
workflow | string | yes | The workflow file in .github/workflows, with no folder. at most 100 characters. |
environment | string | null | no | The deployment environment the job must run in. Left out, null or blank, any job of the workflow. at most 255 characters. |
ref | string | null | no | A branch (main) or a ref pattern (refs/tags/v*, * for any characters) the run must be for. Left out, null or blank, any ref. at most 255 characters. |
permissions | ("diagrams" | "drift:write")[] | no | What its runs may do. Left out, both. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 201 | The new trusted publisher. | TrustedPublisher |
| 400 | The body is not valid. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | A member may not (orgs.forbidden), the plan has no trusted publishers (plan.trusted_publishers_not_included), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation, or the caller is not a member of it. | ErrorResponse |
| 409 | The organisation already trusts that run (trusted_publishers.duplicate), or has twenty (trusted_publishers.limit_reached). | ErrorResponse |
| 422 | GitHub has no such account, or names the repository another (trusted_publishers.invalid). | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 201 answer has the type TrustedPublisher.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
provider | "github" | yes | |
repository | string | yes | The repository, owner/name. |
repositoryId | string | null | yes | GitHub's id of the repository, which a run's token must carry. Null until known: a private repository's is pinned by its first run. |
repositoryOwnerId | string | null | yes | GitHub's id of the repository's owner, which a run's token must carry. Null until known. |
workflow | string | yes | The workflow file in .github/workflows the run must start from. |
environment | string | null | yes | The deployment environment the job must run in, or null for any. |
ref | string | null | yes | The ref pattern the run must match, such as refs/heads/main, or null for any ref. |
permissions | ("diagrams" | "drift:write")[] | yes | diagrams: publish to the organisation's library (and read it and the style rules). drift:write: report drift runs to the Drift tab and read the style rules. |
createdAt | integer | yes | Milliseconds since the epoch. |
createdBy | object | null | yes | Who added it, or null when that account is gone. |
createdBy.id | string | yes | |
createdBy.email | string | yes | |
updatedAt | integer | yes | Milliseconds since the epoch. |
lastUsedAt | integer | null | yes | When a run last signed in with it, in milliseconds since the epoch, or null for never. |
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 |