Organisations
List the groups of an organisation's trusted publishers
A page of the owners the trusted publishers are grouped under (a GitHub owner, an Azure DevOps organisation and project, a GitLab group), each with its id, how many of its entries match q, provider and status, and how many of them were never used or refused last.
GET
/orgs/{org}/trusted-publishers/groupsTL;DR
| Question | Answer |
|---|---|
| What does it do? | List the groups of an organisation's trusted publishers. |
| What does it take? | org in the path, and q, provider, status, cursor, limit in the query string. |
| What does it return? | Status 200 with a body of type TrustedPublisherGroups. |
| What can go wrong? | 400 a query value is not valid, or the cursor is not one this API wrote; 401 not signed in; 403 a member may not see them (orgs.forbidden); 404 no such organisation, or the caller is not a member of it; 429 too many requests; 503 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
A page of the owners the trusted publishers are grouped under (a GitHub owner, an Azure DevOps organisation and project, a GitLab group), each with its id, how many of its entries match q, provider and status, and how many of them were never used or refused last. The first page also has held and totals. The owner and an admin may look.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
Query parameters
| Field | Type | Required | Description |
|---|---|---|---|
q | string | no | Words to look for, without regard to case, in the name, the owner, the repository or project, the workflow file, the pipeline id and the environment. |
provider | "github" | "azure-devops" | "gitlab" | no | Only this CI provider. |
status | "valid" | "invalid" | "never" | no | invalid: its last exchange was refused. never: no run signed in with it yet. valid: not refused since it was last used. |
cursor | string | no | The page's nextCursor from the page before, for the next page. |
limit | integer | no | Groups in the page, 1 to 200. Default 100. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | A page of groups. | TrustedPublisherGroups |
| 400 | A query value is not valid, or the cursor is not one this API wrote. | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | A member may not see them (orgs.forbidden). | ErrorResponse |
| 404 | No such organisation, or the caller is not a member of it. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type TrustedPublisherGroups.
| Field | Type | Required | Description |
|---|---|---|---|
active | boolean | yes | Whether the owner's plan includes trusted publishers. Entries saved before stay, and sign nothing in, while it does not. |
plan | "free" | "pro" | "enterprise" | yes | |
audience | string | null | yes | The audience a GitHub workflow asks GitHub for: this API's origin. Null on a server that cannot exchange GitHub's tokens. |
issuer | string | yes | The issuer of GitHub's tokens. |
azureDevops | object | yes | What an Azure Pipelines token is: its issuer, which ends in the Azure DevOps organisation's id, and the audience Azure DevOps always names. |
azureDevops.issuerPrefix | string | yes | |
azureDevops.audience | string | yes | |
gitlab | object | yes | What a GitLab job's token is: GitLab.com's issuer, the instance an entry names when no host is typed. A GitLab job asks for audience in its id_tokens. |
gitlab.defaultIssuer | string | yes | |
limit | integer | yes | The most trusted publishers an organisation may have. |
held | integer | null | yes | How many trusted publishers the organisation has, whatever the filters. On the first page only, null after it. |
totals | object | null | yes | The entries that match the filters, in all and by CI provider. On the first page only, null after it. |
totals.all | integer | yes | |
totals.github | integer | yes | |
totals.azure-devops | integer | yes | |
totals.gitlab | integer | yes | |
groups | TrustedPublisherGroup[] | yes | By provider, then owner in lower case. |
groups[].id | string | yes | The provider and the owner in lower case, to send as group. |
groups[].provider | "github" | "azure-devops" | "gitlab" | yes | |
groups[].owner | string | yes | A GitHub repository's owner, an Azure DevOps organisation and project, or a GitLab project's group path (after its host when it is not GitLab.com), as typed. |
groups[].count | integer | yes | Its entries that match the filters. |
groups[].never | integer | yes | Of them, the ones no run signed in with yet. |
groups[].invalid | integer | yes | Of them, the ones whose last exchange was refused. |
nextCursor | string | null | yes | Send as cursor for the next page of groups; null on the last. |
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 |