Publishing a provider

Overview

A provider packages pipeline capabilities — a build step, a deploy step, a notifier — as container images plus a manifest saying what each one takes in, what it gives back, and how it is configured. Publishing puts yours in the provider catalog, where other people can install it into their group and wire it into their pipelines. You register once as a publisher, claim a namespace that prefixes everything you ship, and from then on submit one version at a time.

The tier you publish to decides who has to trust what. At the verified tier we review your submission, copy your image into our own registry, sign it and publish it, so consumers trust us rather than you. At the community and private tiers you publish without a review and your registry stays the home of the bytes. A community provider reaches an organisation only once that organisation opts in to the community tier; a private provider belongs to the single organisation you name when you submit, and nobody outside it ever sees that it exists.

Before you start

How it works

Three tiers, three trust stories

Asking for the platform tier in a submission is refused with 403. You cannot assign yourself the verified tier either: you ask for it, and passing review is what confers it. The two self-service tiers you do assign, because their trust signal is the consuming organisation's own opt-in rather than anything we assert.

A submission that leaves the tier out asks for verified. That is the strictest reading of an omission, and it is the usual cause of a first submission being refused with 403 for an unverified namespace — name community explicitly if that is what you meant.

A provider's tier is fixed at its first publication. A later version of the same provider must ask for the tier it already has; moving a community provider to verified means publishing it again under a new id.

Namespaces and provider ids

A provider id is {namespace}.{slug} — acme.deploy, acme.notify. An id with no dot belongs to the platform's own providers (git, docker, aws) and is refused for anyone else. Because your namespace is unique, provider-id uniqueness follows: nobody else can ship acme.anything, and you cannot ship under somebody else's prefix.

Verifying your namespace proves you control the domain or the code-hosting organisation it names. It earns two things: eligibility for the verified tier, and a badge on every provider you publish, which is what an organisation running a verified_only community policy looks at.

What a submission goes through

Nothing about publishing is synchronous. Submitting answers 202 with a submission id and a state of submitted; everything after that happens on its own and you follow it by reading the submission.

Copying and signing both happen inside mirroring; there is no separate step you can see or influence.

changes_requested and rejected both carry the reviewer's reason, and neither can be edited in place: the fix is a fresh submission. A (provider, version) pair is held while a submission for it is still open, and is free again the moment that submission is rejected, has changes requested, is withdrawn, or fails — so the same version number is available for a corrected manifest.

What the platform sets, and what stays yours

At the verified tier the image reference you send is a source, not a destination. The published capability points at our copy of your image and carries the digest we recorded when we pushed it, and we sign that copy with our own key. At the community and private tiers the published reference is yours, unchanged, pinned to the digest you attested and confirmed once at publish time.

Either way, what runs is pinned to an exact digest. Pushing new bytes behind the same tag changes nothing for anyone already running your provider — and there is no way to change a published version, because a published (provider, version) pair is immutable. A correction is a new version.

The provider itself — its name, its description and the shape of the credentials a connection supplies — is taken from the first version that publishes. Later versions carry the same provider block, and anything you change in it is ignored. Only the capabilities, their images and the release notes move from version to version.

Release notes are the one piece of prose that rides along with a version: up to 64 KB of markdown, fixed once the version publishes. Everything else you write about the provider — the long description people read on its page, the categories and keywords they find it by, the worked examples — lives on the provider's marketplace listing, which you edit at any time without republishing anything. See Using providers.

How to

Register as a publisher

Registration is self-service and binds the publisher to the identity that calls it — your user account, or a service account if a release pipeline is going to do the publishing. One identity owns at most one publisher, so decide which identity should hold it before you call.

Pick the namespace carefully. It is the only field you cannot change later, and it is visible to everyone who ever browses one of your providers.

A new publisher starts unverified and active. That is enough to publish to community and private straight away; the verified tier waits until you have proven the namespace. The response carries the publisher id every later call needs, so keep it — you can also find it again from the publisher list.

Prove you own your namespace

Verification is two calls with a manual step in between: ask for a challenge, place the token it gives you, then ask us to look for it. There are two methods, dns and github, and the target you name has to correspond to your namespace — a domain whose first label is your namespace, or a GitHub organisation whose login is your namespace. Anything else is refused with 400, which is what stops namespace acme being verified through notacme.com. A namespace that is a well-known organisation's name is held to more: only dns proves it, and only on a domain that organisation owns, so microsoft is proven at microsoft.com and never at a name somebody created on a shared DNS service, such as microsoft.mooo.com. A namespace Gitmoap keeps for itself is never proven, and the challenge answers 403.

Place the token where the instructions say. For dns, that is a TXT record at _gitmoap-challenge.<your domain> whose value is the token. For github, it is a verification.txt file at the root of a public <your org>/.gitmoap repository, on its main branch, containing the token. Then come back and finish.

Verifying is idempotent: checking an already-verified publisher answers 200 with its current state rather than failing, so a script that runs the check twice is safe.

Asking for manual as the method is refused with 400. A manual grant is a decision platform staff make on your behalf, and it is the route when neither the DNS nor the GitHub proof fits your namespace — write to us instead of calling for it.

Look up a publisher

Publisher profiles are public to anyone signed in, which is how a consumer weighing up a provider finds out who is behind it and whether the namespace is proven. The bound identity behind a publisher is not public — you see it on your own publisher, and platform staff see it everywhere.

Update your publisher profile

The display name, the contact address and the public key are yours to change at any time. The namespace, the account status and the verification badge are not: the first is permanent, and the other two are ours to set.

The public key is recorded on your profile and shown with it. It is not what signs a Verified image: we sign our copy of your image with our own key.

Keep the contact address current. It is where a reviewer's questions land, and it is what a consumer with a broken pipeline will use.

Submit a new provider

Use this for the very first version of a provider that is not in the catalog yet. It creates a submission, not a catalog entry — nothing about the provider is visible to anyone else until the submission reaches published.

The body carries the whole candidate version: a contract version of 1, the provider block, the version, every capability with its image reference and digest, the tier you are asking for, the owning group if the tier is private, and optional release notes. Between one and thirty-two capabilities, each with an id prefixed by the provider id, each with a digest of the exact form sha256: followed by sixty-four hex characters. The body accepts no fields beyond the ones the card lists — a misspelt field name is a 400, not a silently ignored value.

Write the descriptions for the people who will use the provider, not for yourself. A capability's description is what somebody reads when they are deciding whether to pick it; a port's description is rendered beside that port in the pipeline editor, so it should say what flows through, what to connect it to and what happens if you leave it unwired — never a container path or an internal error code. A port description is optional and capped at 400 characters, but a port that ships without one leaves whoever wires it guessing.

Submit a new version of a provider you own

Once a provider exists, further versions go to its own submission endpoint. Ownership is checked against your publisher, the manifest's provider id has to match the one in the URL, and the tier has to match the tier the provider already has. A provider that has never published answers 404 here — its first version goes through the new-provider call instead.

Version numbers are strict: a leading v and three numeric parts, v1.0.0. No pre-release suffix, no build metadata, no ranges, no latest. A version that has already published is refused with 409, because a published version is immutable.

Follow a submission to the end

A submission is the only place the outcome lives. Read it to see the current state, the reviewer's notes if a decision has been made, and — once it has published — the digests that were recorded.

A failed self-service check writes its reason into the same notes field a reviewer would use, so verification_failed tells you what did not resolve without your having to guess.

Both reads are restricted to the owning publisher and platform staff, because a submission carries review notes that are nobody else's business. Once a submission reads published, the version is in the catalog and an organisation that accepts your tier can install it — see Using providers for what a consumer does next.

Withdraw a submission

Withdraw when you spot a mistake before a decision has been taken, or when you want to free a version slot so you can submit a corrected manifest under the same version number.

Withdrawal is only possible while the submission is still waiting on a decision or still being checked. Once it has been approved — which is when the copy-and-sign work starts — or once it has reached any final state, the call is refused with 409, because approved work holds platform resources a withdrawal cannot cleanly interrupt. A submission that already ended in changes_requested or rejected is final too: there is nothing left to withdraw, and its version slot is free already.

Deprecate a version

Deprecating is how you steer consumers off an old version without breaking them. A deprecated version still runs, and pipelines pinned to it keep working; what changes is that a pipeline referencing it gets a non-blocking warning when it is validated, and the version shows as deprecated wherever it is listed.

Deprecating does not remove the version from the list of versions a pipeline may pin, and it does not change which version is newest — a deprecated version can still be the latest one. Deprecating an already-deprecated version is a no-op. A version that has been sunset cannot be deprecated, and the request answers 409: sunset is permanent. If a version has to stop working altogether, that is a platform decision with a grace window attached, not a publisher one — ask us.

Bring a deprecated version back

Deprecation is reversible. Restoring returns the version to active, and the warning consumers were seeing stops.

A version that has been sunset by the platform is a different matter and cannot be restored this way; the call answers 409. Deprecate and restore are the only two lifecycle moves a publisher has. Sunsetting is a platform action, taken with a grace window attached, and no call reverses it — the way past a sunset version is a replacement version.

Reference

Limits

One publisher per identity. A second registration from the same account or service account is refused with 409 and nothing is created. If you need a separate namespace, register it from a separate identity — a service account is the usual answer for a namespace that a team, rather than a person, should own.

Twenty open submissions per publisher. A submission occupies a slot from the moment you submit until it settles — published, rejected, changes requested, withdrawn, or failed. An approved one still occupies its slot right through the copy-and-sign step, and so does one the automated digest check is still running against. At twenty, a further submit is refused with 429 TOO_MANY_REQUESTS and no submission is created. Free a slot by withdrawing something you no longer want, or wait for a pending decision.

Thirty-two capabilities per submission, and at least one. A provider bigger than that has to split into two providers under the same namespace.

Field sizes the API checks. When you register or update a publisher: a namespace of 3 to 32 characters and a display name of 1 to 80. When you submit: an image reference of at most 512 characters, a port description of at most 400, and release notes of at most 64 KB. Each of these is refused with 400 and the message names the field.

None of these ceilings move with a plan. They are platform limits on the publishing surface rather than namespace quotas, so they are not on your group's usage page and a plan upgrade does not raise them. If one of them is genuinely in your way, get in touch through the contact address on your publisher profile.

Troubleshooting

FAQ

Related