Skip to content

Standards sets

A standards set is a named, versioned collection of statements that repositories subscribe to. You write and publish sets under Standards → Standards sets (/standards/standards-sets). Open Standards and choose the Standards sets tab.

The page is headed Standards sets, with the line “Named, versioned collections of statements that repos subscribe to.” Each row shows the set’s name and, when it has one, its description. A badge on the right shows the published state:

BadgeMeaning
Published vNThe set has a published version; N is the latest.
No published version yetThe set has only a draft.

When there are no sets, the page reads “No standards sets yet. Create one to start authoring statements.” Choose a row to open the set.

Choose Create set. The Create standards set modal says “A named, versioned collection of statements a repo can subscribe to.” and has two fields:

  • Name is required. Leaving it blank shows “Enter a name”.
  • Description (optional) says what the set covers.

Create set stays disabled until the name is not blank. Both fields are trimmed. Cancel closes the modal. On success, the dashboard opens the new set’s detail page.

The detail page (/standards/standards-sets/:setId) shows the set’s name, its description and a badge: Published vN, or Not yet published when no version has been published.

The Draft statements section lists the statements in the current draft. Each row shows the statement, an enforcement badge and an Edit button. When the draft is empty, it reads “No statements in this draft yet.”

BadgeMeaning
StatedThe statement has no check behind it.
Non-blockingA check runs, but a failure only warns.
EnforcedA check runs and a failure blocks.

Add statement and Edit open the same form:

  • Statement is required. Leaving it blank shows “Enter a statement”.
  • Enforcement check (optional) names a check, such as ci/lint. The hint reads “A newly added check arrives non-blocking — you can see who would fail before anyone does.”
  • Blocks merges is a toggle that appears once a check is entered.

Choose Save draft to save, or Cancel to close the form. Edits change the draft only; repositories do not see them until you publish.

Choose Publish. The Publish this set dialog reads: “Publishing promotes the current draft to version N+1 and propagates it to every subscribed repo immediately.” where N+1 is the next version number. Confirm with Publish, or choose Cancel. The API then opens a new draft cloned from the published version.

Once a set has a published version, an Adoption section appears. It shows the same Who would fail panel described in Standards. For each check that is not yet blocking, Promote to blocking opens a confirm dialog that says how many repositories would fail, how many are excepted and how many are not running the check. Confirming switches those repositories to blocking and shows a summary, “Promoted check: N repos switched to blocking.”, with a Dismiss button. Repositories that were skipped are listed with a reason: Excepted, “Uses the organization’s default checks”, Not running this check, Already blocking or Could not update.

Only published sets can be subscribed to. Pick one with the Standards set select on the repository’s Standards tab. See Standards set.

The pages do not hide their buttons. The API checks the grant when you act, and a request without it is refused with a 403 error that the dashboard shows. Reading needs only organization membership.

ActionGrant
Create a setstandards-set-create
Add a statementstandard-create
Edit a statementstandard-update
Publish a setstandards-set-publish
Promote a check to blockingstandards-set-publish

All four grants belong to the Standards bundle. Owners and admins hold every bundle. See Team & Roles for roles and grants.

MethodPathUsed for
GET/api/orgs/:orgId/standards-setsThe list
POST/api/orgs/:orgId/standards-setsCreate a set
GET/api/orgs/:orgId/standards-sets/:setIdThe detail page
POST/api/orgs/:orgId/standards-sets/:setId/standardsAdd a statement
PUT/api/orgs/:orgId/standards-sets/:setId/standards/:standardIdEdit a statement
POST/api/orgs/:orgId/standards-sets/:setId/publishPublish the draft
POST/api/orgs/:orgId/standards-sets/:setId/checks/:checkName/promotePromote to blocking