Provider policy and administration

Overview

Decide which pipeline steps your organisation is willing to run at all. You install a provider into a group so every repository under it can use it, pin the version it runs at, restrict the range of versions a pipeline author may name, and set the trust posture that decides whether third-party providers are admitted alongside the ones we build. Everything here is inherited: a decision taken on a top-level group applies to every repository beneath it until a nearer group overrides it.

Behind the shared catalog sits a platform-administration surface — the submission review queue, publisher verification, editorial featuring, and withdrawing a version from service. Those need the platform-admin role, which is separate from being an Owner of your own group.

Before you start

A brand-new top-level group starts with every Platform-tier provider already installed at its newest version, so a first pipeline that checks out code and builds an image works without anybody installing anything.

How it works

Three separate decisions govern whether a pipeline step is allowed to run, and they are answered in a fixed order. Knowing which of the three refused you is most of the work of fixing it.

1. Is the provider installed, and at what version? One record per group and provider, resolved nearest-first up the group tree.
2. Does the organisation accept the provider's trust tier? One record per group, owned by Owners rather than Maintainers, and resolved setting by setting rather than record by record — each of its four settings takes its value from the nearest group that set that one setting.
3. Is the exact version the pipeline resolved to permitted? The install's allow-policy, plus the version's own lifecycle.

Where an install is resolved from

Repositories hold no installs. A run in a repository looks at the repository's own group first, then each ancestor group outward, and takes the first record it finds:

Each row you read back says where it came from. inherited tells you the decision was taken above you, and source_scope_id names the group that took it — so "who turned this on and where do I go to change it?" is answerable from the listing. When the deciding group is one you cannot read, the functional half of the row still comes back and the provenance is hidden; you see what applies without learning who is in a group you are not a member of.

The walk is per provider and the nearest record wins outright — a child's record is never merged with a parent's, it replaces it. That leaves two ways to change what a group gets:

Disable and uninstall are not two words for the same thing, and picking the wrong one is the most common surprise on this page. Uninstalling in a child group where the install actually lives at the parent removes nothing and changes nothing.

An install also carries an override_parent flag. It is recorded and handed back to you, but it changes nothing about how installs resolve, because the nearest record already wins. The flag earns its keep on the trust policy below, which resolves setting by setting rather than record by record.

The four trust tiers

Every provider in the catalog carries a tier, and the tier is what your acceptance policy talks about.

Community and Private providers are pinned to an exact image build that cannot be swapped after publication, but nobody at Gitmoap has read them. That is why admitting them takes two independent decisions: an Owner sets the organisation's posture on the tier, and the Maintainer who installs one specific provider acknowledges that they are taking responsibility for it. Either gate alone leaves a hole, so both are enforced — the acknowledgement is asked for even when the organisation already admits the tier. The two tiers start from opposite postures: Community is closed until an Owner opens it, while your own organisation's Private providers are open until an Owner shuts them off.

A Private provider belongs to exactly one organisation and is invisible outside it. Asking for one that belongs to somebody else answers 404, the same way a private repository does, so its existence is not leaked.

When each check runs

Installing runs the tier check and the acknowledgement check immediately, but only for a Community or Private provider — those are the two tiers with a gate at install time. A Platform or Verified provider installs with no tier check at all. That means a Verified provider your organisation has stopped accepting still installs cleanly, and then never runs — which is exactly what tier_accepted: false on its row is telling you.

The policy is checked again every time a pipeline is triggered, against the repository's own group chain — which means an install that was legal when it was made stops running the moment an Owner narrows the policy. A trigger that fails these checks is refused with 403 PROVIDER_VALIDATION_FAILED, and the response names one of these reasons for each offending step:

How to

See which providers a repository can run

This is the view that answers "why will my pipeline not start?", because it resolves the whole group chain exactly the way a trigger does. Each row tells you the version that applies, whether it was inherited and from where, whether a newer version has been published, and — through tier_accepted — whether the organisation's policy will actually let it run. A provider that is installed and enabled but shows tier_accepted: false is one an Owner has to admit before any pipeline can use it.

See what a group has installed

The group view is the one to use before you change anything, because it resolves this group's own chain — what a repository directly under it sees, before any subgroup adds a record of its own.

Check one provider

When you already know which provider you are asking about, read it by its id rather than filtering the whole list. A provider that is installed nowhere in the chain answers 404 rather than an empty row, which is the difference between "somebody turned this off" and "nobody ever set it up".

Provider ids are lowercase slugs. The ones we publish are bare — git, docker, aws — and a third-party id always carries its publisher's namespace, as in acme.deploy.

The repository view answers for the exact chain a run evaluates, so it is the one to quote when a pipeline author says a step will not start.

Install a provider into a group

Installing pins a version. Leave the version out and the provider's newest published version is pinned; name one and it must exist in the catalog. You can restrict the versions a pipeline may name in the same request, and you can set the install to follow the newest published version instead of a fixed pin.

Installing a provider the group already has replaces the record rather than failing, and does not consume a second install slot — but it replaces the whole record, not just the pinned version. The version, the version allow-policy, the latest-tracking setting and the enabled flag all come from the new request, so anything you leave out reverts to its default and a provider you had disabled here comes back on. When moving the version is the whole point, use the upgrade task below: it moves the pin and touches nothing else, and it honours the changelog-review setting.

For a Community or Private provider, send acknowledge_unverified: true. Without it the install is refused with 403, even when your organisation's policy already admits the tier — the two gates are deliberately independent, and we record who acknowledged the install and when.

Restrict which versions a pipeline may name

An install's allow-policy governs which exact versions a pipeline author may declare. It comes in three shapes:

Range bounds are compared as version numbers, not as text, so v1.10.0 is correctly newer than v1.9.0. Whatever the policy allows, the version a run actually executes is always one exact version, baked onto the run — a range never means "float".

The same request carries the latest-tracking switch. With tracking on, a step that names no version resolves to the provider's newest published version at the moment the run is triggered, still within the allow-policy and never a withdrawn version. Each run is still reproducible because the resolved version is fixed onto that run; only the next trigger moves forward. Tracking is a per-install choice, so one group can follow the newest release while another stays pinned.

Narrowing the policy so that it excludes the version the install is pinned to is refused with 400 rather than saved, because it would leave the install unable to run anything. Upgrade to a permitted version first, or turn on latest-tracking, which makes the pin unused.

Move an install to a newer version

Upgrading changes the pinned version and nothing else — it does not re-run the tier or trust checks, because the provider was already admitted when it was installed. Upgrading to the version already pinned is a no-op that returns the current record.

When the organisation's policy requires changelog review, send changelog_acknowledged: true with the request or it is refused with 403. The acknowledgement is recorded with the upgrade, so an audit of who moved a provider forward and on what basis is answerable later.

Turn a provider off without losing the install

Disabling writes an explicit refusal at your group. Where the provider was installed at a parent, that refusal is how a child group opts out without touching the parent's decision, and it survives everything the parent does afterwards. The provider must exist in the catalog; disabling an id nothing has published is refused with 404.

Re-enabling reverses it, leaving the version pin and the allow-policy exactly as they were — where there was an install here to begin with. Where the refusal was the only thing the group had, a child opting out of a provider installed above it, there is no pin to restore, and the record that is left still shadows the ancestor's install. Steps that name no version then fail with provider_version_unspecified. Uninstall that record instead and the group goes back to inheriting.

Remove an install

Uninstalling frees an install slot against the group's cap. A second uninstall of the same provider answers 404, because there is no longer a record to remove.

Read the tier policy in force

The policy read resolves the whole chain and applies defaults, so it always answers even when nobody has ever set one. inherited and source_scope_id tell you whether the answer was decided here or above; accepted_tiers is the short version of the answer.

The repository view answers the same question for the exact chain a trigger evaluates, which makes it the one to check when a run was refused for a tier reason.

Decide which provider tiers your organisation accepts

Four decisions live in the policy:

Platform providers are always accepted and have no setting. verified_only is the useful middle ground for an organisation that wants community velocity without anonymous authors.

Latest-tracking is the one route past require_changelog_ack. An install that follows the newest release advances without an upgrade, and the acknowledgement is asked for on upgrades. Turn tracking off on the installs you want a human to look at.

Setting override_parent stops the walk at your group, so an ancestor's policy is ignored for every setting rather than merged setting by setting. What you leave out then falls to the defaults in the table above — not to the value the parent had.

Narrowing the policy does not touch existing installs — the records stay exactly where they are, and start being refused at trigger time. Check the group's provider list afterwards: any row showing tier_accepted: false is an install that no longer runs.

Fall back to the parent's policy

The removal answers with the policy that applies afterwards, so you can see immediately what the group fell back to. It only works where the group has a policy of its own: a group that was already inheriting has nothing to remove and answers 404. Read the effective policy first — when it comes back inherited, the group to change is the one named as its source.

Work the submission review queue

Everything from here on is platform administration, and needs the platform-admin role.

Submissions for the Verified tier wait in a review queue. The queue answers with the newest first and defaults to submissions that have been sent in and are waiting for a reviewer; ask for another state to see what was approved, rejected, sent back or withdrawn. Page sizes are clamped between 1 and 100.

Community and Private submissions are not reviewed. They are self-service: we confirm that the exact image build the submission names resolves in the author's registry, then publish it with no reviewer in the loop. The trust decision for those tiers belongs to the organisations that install them, which is what the trust policy is for.

Approve, reject or send back a submission

Approving is what starts publication. The submission is marked approved and we then copy its image into our own registry and sign it; the catalog gains the version only when that finishes, so an approval is not itself a publication. Watch the submission's state to see it through.

Rejecting is terminal. The publisher cannot revive a rejected submission and has to send a corrected one. A reason is required, and it is what the publisher sees.

Requesting changes is the softer version: the submission stops being reviewable and the publisher sends a corrected one afresh, with no rejection on the record. A reason is required here too. All three decisions release the slot the submission was holding against the publisher's limit on submissions awaiting review, so a publisher is never left blocked by a queue you have already worked.

All three refuse with 409 on a submission that is in any other state, which is what a second reviewer acting on a stale queue sees. Approving refuses with 422 when the publisher's Verified eligibility was withdrawn between submission and approval — a deliberate re-check, because eligibility is what earns the reviewed tier in the first place.

Grant or revoke a publisher's Verified eligibility

Verified eligibility is what lets a publisher submit to the reviewed tier, and it lights the verified-namespace badge on everything else they have published. Publishers can also earn it themselves by proving they control the domain or organisation their namespace is named for; this action is the manual path, for support and for revocation.

Revoking blocks future approvals and clears the badge. It does not unpublish anything already in the catalog. It does have one run-time consequence: an organisation whose Community setting is verified only stops accepting that publisher's providers from the next trigger onwards, refusing those steps with provider_namespace_not_verified. Withdraw a specific version if taking something out of service for everyone is what you need.

Feature a provider in the marketplace

Featuring is editorial placement: a rank that decides the "start here" ordering in the marketplace and lifts the provider in the default relevance sort. Lower ranks place higher, and clearing the rank removes the provider from the featured set without touching anything else about it.

A Private provider cannot be featured and the request is refused with 400. Featuring is a global act on a global list, and a provider only its owning organisation can see has no place on one.

Withdraw a version from service

During the grace window, runs that name the version still work and carry a warning, so the people affected find out before anything breaks. After it, the version is refused. A reason is required and is the explanation consumers are given.

Reference

Reading what applies

Managing installs

The trust policy

Platform administration

Limits

A group holds a limited number of provider installs. The limit is per group, not per organisation, so each group in a tree has its own budget.

Reaching the limit refuses the install with 429 TOO_MANY_REQUESTS, and nothing is written — no partial record, no half-counted slot, and the providers you already had are untouched. Only a new install counts: re-installing a provider the group already has replaces the record and consumes nothing further, and upgrading, disabling, enabling and editing an install's version policy are all free. Uninstalling returns the slot immediately.

A new top-level group is created with every Platform-tier provider already installed, so it starts with those records counted against its budget rather than at zero.

Two ways to get more room. Uninstall providers the group no longer uses — a group that inherits most of what it needs from its parent rarely needs many records of its own. Or raise the limit: moving to a higher plan raises it as shown above, and Owners can request an increase beyond the plan default, which we can raise as far as 50 000 for one group.

The group's limits view counts the installs the group holds against its limit, read from the same counter the refusal uses, so the number you see is the number you will hit. The shorter usage view does not carry it — it covers storage and pipeline consumption for the whole organisation.

Troubleshooting

Related