Using providers

Overview

A provider is a step your pipeline can run — cloning a repository, building an image, pushing it to a registry, deploying it, telling a channel it worked. The marketplace is where you find one, read what it does, and see which versions it has published. A connection is how you hand it the credentials it needs to reach your own systems, stored once at the group or repository level and picked up by every pipeline underneath.

The two halves are separate on purpose. Reading the catalog tells you what a provider can do and what shape of credential it wants; creating a connection tells one group or one repository which account to use when it does it. You can browse the whole marketplace without owning anything, and you can hold a dozen named connections for the same provider — one per environment — without a pipeline ever having to guess which is which.

Quick start

Before you start

How it works

A provider, a version, a capability, a port

Four nested things, and a pipeline node names the innermost one.

A provider is the unit you trust and connect to. A version is immutable once published — the same version always resolves to the same container image, which is what makes a run reproducible. A capability is a single runnable step, identified as provider:name, and it belongs to a stage: source, build, test, publish, deploy, notify or custom. Ports are its typed inputs and outputs; a pipeline connects one node's output port to another node's input port, and the types have to match exactly. A capability's own settings — the cluster to deploy into, the bucket to write to — are node configuration rather than ports, though a capability may mark some of those keys as bindable, and each of those also shows up as an optional input port so an upstream node can supply the value instead. The credentials port type is where the two halves of this page meet: a credentials input with nothing wired into it is filled from the connection resolved for that node, and only a capability that deliberately emits credentials as an output can feed one over an edge you draw.

Capability reads default to the provider's latest version. Pass version to read the capabilities of an older one, which is what you want when a pipeline is pinned and you are reading the manifest it actually runs.

Some capabilities declare input groups — a set of optional input ports where exactly one, at most one, or at least one may be wired. A capability that deploys from a zip or a container image says so this way, and the editor refuses the impossible combination while you are drawing the pipeline rather than after a run has started.

Where a connection lives, and which one a node gets

A connection is attached to one group or one repository, and it carries a name you choose: aws-prod, aws-staging, docker-ci. A name is unique within a scope across every provider: a group can hold aws-prod and aws-staging side by side, but not two called aws-prod — and not a prod for one provider alongside a prod for another. Naming a connection after the provider it belongs to is what keeps you out of that collision. Resolution then matches on the provider and the name together, so a repository's aws-prod shadows the group's aws-prod and nothing else.

When a pipeline in a repository triggers, connections are gathered from the repository first, then from its parent group, then that group's parent, and so on outwards. The first (provider, name) seen wins:

That is the whole override model: define a connection once high up, and shadow it lower down by defining the same provider and name closer to the repository.

A pipeline node picks its connection by name. If a node names one, that exact (provider, name) must resolve or the run fails to start. If a node names none, the connection auto-resolves when exactly one connection for that provider is in scope — and refuses when there are two, because guessing between production and staging is the wrong kind of convenience. Having no connection for a provider is not an error: most capabilities need no credential at all, and a run only fails if a step actually tries to use one.

Which connection each node uses is decided once, when the run is created, and does not change for the life of that run. The credential values behind it are read again as each step starts, so a rotation reaches every step that has not started yet, and deleting a connection makes a step that has not started yet fail when it reaches for it. Neither disturbs a step that is already running.

How a connection authenticates

Two modes, chosen at creation and fixed for the life of the connection.

A static connection's values are encrypted when written and are never returned by any endpoint. What comes back is the names of the fields the connection holds, so you can see that a credential is present and which fields it covers without the value ever leaving storage again. A federation connection stores no secret whatsoever — the pipeline exchanges a short-lived token for a role at run time. AWS is the cloud a federation target names, and the role is a full IAM role ARN. Federation is only offered by providers that advertise it, and asking for it from one that does not is refused at creation.

Because the mode is fixed, switching a connection from stored keys to federation means creating the new one and deleting the old.

What is recorded

Creating, rotating and deleting a connection are recorded in the audit log as changes, and so is writing a marketplace listing. Reading a single connection, and resolving a repository's connections, are recorded as sensitive reads — listing them is not, and no catalog read is recorded at all. If you are auditing who looked at your credential configuration, those sensitive reads are the entries to look for.

How to

Browse the marketplace

The browse list is the provider grid: name, one-line description, categories, the trust tier, whether the publisher's namespace is verified, and how many organisations have installed it. Narrow it with q for free text over names, descriptions and keywords; with category, tier and verified_only for facets; and with featured for the editorially curated shortlist. owning_group narrows the list to one organisation's private providers, and answers nothing at all to somebody outside that organisation. Sort by relevance, installs, name or recently_updated.

Page size is clamped to 1–100 rather than refused, so a limit outside that range quietly gives you the nearest legal page. The next_token you get back is tied to the filters and the sort that produced it: change either while paging and the token is refused, so re-run the search from the first page after every filter change.

Install counts are omitted for the platform's own providers — they ship with every organisation, so a count would say nothing useful. Their signal is the tier badge instead.

Filter the marketplace by category

Categories are a fixed, curated list — source-control, build, test, quality, security, release, deploy, infrastructure, notify and other — and each comes back with a live count of the providers you can see. A private provider counts only for members of the organisation that owns it, so two people can legitimately see different numbers.

Read a provider's marketplace page

Before you connect anything to a provider, read its page. It carries the long-form README, the worked examples its publisher wrote, the publisher badge, and the full version history with a changelog and a lifecycle state per version.

Three things on that page are worth reading properly:

• The tier. platform providers are built and run by us. verified providers are third-party but reviewed and re-published by us. community providers are published directly by their author from the author's own registry. private providers belong to one organisation and are invisible outside it.
• The lifecycle state of the version you intend to pin. active is normal. deprecated still runs, with a warning. sunset runs only inside its grace window, after which a pipeline referencing it fails to start.
• The examples. Each names the capabilities it exercises, so an example is also a shortcut to the capability you want.

Check a provider's credential shape

The provider record carries the schema for its credentials — the exact field names and types a connection must supply — and the authentication modes it supports. Read this before creating a connection, because credentials are validated against it and a mismatch is refused outright.

Compare a provider's published versions

Versions come back newest-first, each with when it was published, who published it, whether its image is signed, and its lifecycle state. A sunset version also carries the moment it was sunset and the moment its grace window closes — the deadline for moving anything pinned to it. Versions are strict semantic versions with a leading v, like v1.4.0 — there is no floating range and no latest tag to pin to, because a pipeline that silently changes what it runs is not reproducible.

Read one published version in full

A single version read returns the whole manifest: every capability at that version, with its ports, its configuration schema, its default timeout, and the exact image build the version resolves to. This is the definitive answer to "what does my pinned version actually run".

See what a provider can do

The capability list for a provider, at its latest version unless you pin one. Filter by stage_type when you know which part of the pipeline you are filling — asking a provider for its deploy capabilities is usually faster than reading all of them.

Read a capability's ports before you wire it

A capability read is what you consult while drawing a pipeline. It gives you the ports — each with a name, a type, whether it is required, whether it takes one source or several at once, and a description written by the provider's author saying what to connect to it and what happens if you do not — plus the configuration schema for the node, which configuration keys accept a value produced by another node, and any input groups constraining which optional ports may be used together.

Port types match exactly; there is no coercion. A port named source always carries a git reference, artifact always carries an artifact, and so on across the whole catalog, so two ports that share a name always carry the same type. A port can also name the exact shape it carries — s3.object/v1 on an artifact port, aws.ecs.task-definition-arn/v1 on a custom one, which is how a provider describes a payload the built-in types have no name for. Two ports connect only when both the type and the named shape agree; a port that names no shape takes any payload of its type.

Connect a provider once for a whole group

This is the usual place to put a connection. A connection on a group is available to every repository and every nested group beneath it, so one aws-prod at the top of your organisation serves everything under it.

Give it a provider_id, a name and the credential fields the provider's schema requires. The name is lowercase letters, digits and hyphens, one to sixty-four characters, no leading or trailing hyphen — aws-prod, docker-ci, registry-eu. Pick the name you want pipeline authors to type, because that is exactly what they will type.

For a connection that stores no secret, set auth_mode to oidc_federation and supply federation_target — the cloud (aws), the IAM role ARN to assume, and optionally the audience and region — with no credentials block at all. The provider has to advertise federation for this to be accepted.

Override a group's connection for one repository

A connection created on a repository shadows any connection with the same provider and name inherited from above. Use it when one repository deploys somewhere the rest of the group does not, or when you want to narrow a single repository's blast radius to a credential of its own.

Everything else — the request shape, the name rules, the two authentication modes — is identical to the group case.

List the connections defined on a group or repository

Both listings show what is defined directly on that scope, newest first, with nothing inherited folded in. That is the view you want when you are auditing what one group owns, and the wrong view when you are asking what a pipeline will actually get — for that, resolve.

See which connections a repository actually resolves

This is the one to reach for when a pipeline cannot find its credentials. It walks the repository and every group above it and returns the merged result — one entry per (provider, name), each marked as inherited or not, and each naming the scope it came from.

Two things it will tell you that a plain listing cannot: whether the connection a node names is reachable from this repository at all, and whether two connections for the same provider exist in scope, which is what turns an unnamed node into an ambiguity error.

An entry inherited from a group you cannot read comes back with its details blanked — the provider and the name survive, because you need to know the connection applies, but the field names, the creator and the source group do not. A row that looks half-empty is that, not a broken connection.

Inspect one connection

A single-connection read returns the same shape as a listing row, for one connection. Credential values are not part of that shape at any scope — there is no endpoint, flag or role that returns them.

Single reads are recorded in the audit log as sensitive reads.

Rotate a connection's credentials

Rotating means sending a fresh, complete credentials object. Fields you send are written over the old values; fields you leave out are removed from the connection. Send the whole set every time, not just the one that changed, or the connection ends up missing the fields you omitted and every pipeline using it starts failing.

The new credentials are validated against the provider's schema first, so a rotation with the wrong field names is refused before anything is overwritten. A successful rotation stamps the connection's last-rotated time. That stamp is empty until the first rotation, so a connection showing nothing there is still running on the credential it was created with — which is what to look for when you are auditing credential age.

You can also update config_overrides without touching credentials — send it alone and the stored secret is untouched.

The authentication mode cannot be changed. Sending credentials to a federation connection, or a federation target to a static one, is refused; create a new connection and delete the old instead. What a federation connection can change is where it points: send a new federation target to move it to a different role, audience or region.

Delete a connection

Deleting a repository-level connection that was shadowing an inherited one un-shadows it: the group's connection with the same provider and name starts resolving again on the next trigger. That is usually what you want when you created an override by mistake, and worth checking when you did not.

Deleting is not idempotent — the second delete of the same connection answers 404.

Deleting the group or repository a connection lives on takes its connections with it, credentials included. That is one more thing to weigh before deleting a scope that other people's pipelines run under.

Write the marketplace listing for a provider you publish

If you publish a provider, its listing is the page everyone else reads — the README, the categories it appears under, the search keywords, the homepage and repository links, and the worked examples. It is editable independently of your versions, so fixing a typo in the README does not mean publishing a release.

The enforced shape: one to three categories, at most ten keywords, and at most ten examples, each with a title of at most 120 characters, a description of at most 500, and a snippet of at most 8 KB. A keyword is 1 to 31 characters of lowercase letters, digits and hyphens, and cannot open with a hyphen. The README is at most 128 KB, and the homepage and repository links have to be https://. Every capability an example names has to exist in one of your published versions, which is checked when you save.

Fields you leave out are unchanged; sending an explicit null clears one. You have to own the provider's namespace as an active publisher; the platform's own providers have their listings maintained with the provider itself and refuse this call.

Reference

The marketplace and catalog reads:

Connections on a group:

Connections on a repository, and the resolved view:

Limits

Connections are capped per scope, and a group and a repository each get their own allowance — a group at its cap does not stop a repository underneath it from holding its own.

At the cap, creating another connection is refused with 429 TOO_MANY_REQUESTS. Nothing half-exists afterwards: no connection appears in the list, the credentials you sent are not kept, and the connections you already have are untouched. Deleting a connection frees a slot immediately.

Reading the marketplace is not capped, and neither is rotating a connection you already hold — only creating a new one counts against the number.

If you need more, an Owner can request a limit increase for the namespace, which raises this single number without changing your plan. Increases are granted up to a ceiling of 10 000 connections per scope. The group's limits view shows the effective number and how many of them you have used, which is the same number enforcement checks, so the two can never disagree.

Troubleshooting

FAQ

Related