# Marketplace & Deployments (/docs/connectors/marketplace-and-deployments)



Once an action behaves and is certified, two systems move it into the **action
inventory** safely: **integration deployments** give connector behavior an
immutable, promotable identity, and the **extension marketplace** distributes and
installs it with destructive-change guardrails.

<Callout type="info" title="Distribution today, purchase on the roadmap">
  The marketplace here distributes and installs connector *behavior* — code and
  manifests — with promotion guardrails, and that ships today. An action can now
  carry a resolved [price](/docs/connectors/action-pricing) and an
  [assurance tier](/docs/connectors/assurance), both opt-in. The marketplace
  itself still sells nothing. A worker's capped spend on a priced action now
  settles to the balanced ledger as showback, but an action price carries no
  payee — so nothing is bought *from* a publisher and no seller is paid.
  Crediting a marketplace publisher for a purchased action is
  <Status kind="roadmap" />.
</Callout>

## Integration deployments [#integration-deployments]

A connector integration deployment (`docs/connectors/integration-deployments.md`)
is an **immutable manifest identity** for connector behavior that is safe to
promote, diff, activate, and execute. It records provider identity, version,
environment, integration key, function inventory, manifest hashes, activation
status, and creator — but never source code, credentials, OAuth tokens, webhook
secrets, API keys, or raw request bodies.

The canonical lookup key is:

```text
tenant_id + environment + integration_key + version
```

Create one with `CreateConnectorDeployment`. Compiled-provider deployments can
**omit** `functions` and `manifest` — the service projects executable actions,
syncs, webhooks, events, and lifecycle functions from the registered catalog;
uploaded manifests must declare their functions explicitly and are validated
against the current registries.

<Callout type="info" title="One active deployment per (tenant, env, integration key)">
  Only one deployment can be active for a given tenant, environment, and
  integration key. Activating a successful deployment supersedes the prior active
  one atomically, and rollback is just activating a previous successful deployment
  — the old deployment stays immutable, only the active pointer moves.
</Callout>

Always `DiffConnectorDeployment` before promotion. It compares two explicit
deployment ids, or the active deployments for two environments, and returns
**stable reason codes** for added, removed, and changed functions — provider
changes, schema changes, action/trigger key changes, manifest-hash changes, and
version-only changes. Activation rejects destructive changes (removed functions,
changed provider/schema/action/trigger identity) unless the caller sets
`allow_destructive`; version-only changes are non-destructive. Mapper bindings
ride in the function manifest hash, so a changed mapper appears here as a data
contract change (see [Data Mapping](/docs/connectors/data-mapping)).

At execution, `ExecuteAction` can resolve by fully-qualified `action_key`, by
`deployment_id + function_name`, or by active `environment + integration_key +
function_name`. The execution ledger row is stamped with a redacted
`connector_deployment` object as audit context — the execution boundary still owns
credential resolution, routing, circuit breaking, idempotency, and provider
invocation.

## The extension marketplace [#the-extension-marketplace]

The extension marketplace distributes connector extensions through an HTTP gateway
(`transport/gateway/marketplace/`, backed by `application/extensionmarketplace`
and the catalog `pkg/marketplace`). Uploaded artifacts are verified with **Ed25519**
signatures. The routes:

| Method & path                                         | Purpose                         |
| ----------------------------------------------------- | ------------------------------- |
| `GET /`                                               | Search publications.            |
| `POST /`                                              | Publish a publication.          |
| `GET /installations`                                  | List installations.             |
| `GET /{name}`                                         | Get the latest version.         |
| `GET /{name}/versions`                                | List versions.                  |
| `GET /{name}/{version}`                               | Get a specific version.         |
| `POST /{name}/{version}/install`                      | Install a version.              |
| `POST /{name}/{version}/disable`                      | Disable an installation.        |
| `POST /{name}/{version}/uninstall`                    | Uninstall.                      |
| `POST /{name}/{version}/deprecate`                    | Deprecate a publication.        |
| `POST /{name}/{version}/withdraw`                     | Withdraw a publication.         |
| `POST /{name}/{version}/quarantine` · `/unquarantine` | Quarantine or clear quarantine. |

Mutations accept an &#x2A;*`Idempotency-Key`** header so a retried publish or install
does not double-apply, and an `expected_record_version` field to enforce optimistic
concurrency — a stale version is rejected rather than silently overwriting a
concurrent change.

### Dry-run previews and destructive operations [#dry-run-previews-and-destructive-operations]

A `dry_run&#x60; install or publish returns a &#x2A;*`RuntimeChangePreview`** describing what
*would* change — added/removed actions, triggers, and resolvers, changed OAuth
scopes, and a `destructive&#x60; flag. When an operation is destructive, the preview is
a &#x2A;*`DestructiveOperationPreview`** carrying an `operation_approval` token and a
per-impact breakdown.

<Callout type="warn" title="Destructive ops require a dry-run first">
  A destructive marketplace operation cannot execute directly. You must issue a
  `dry_run` preview first to obtain the `operation_approval` token, then replay the
  operation with that token. The token is scoped to the previewed change — there is
  no way to approve a destructive install or uninstall without seeing its impact
  preview first.
</Callout>

Marketplace installs also evaluate the manifest's
`runtime.certification_requirements` against tenant-scoped scorecards and fail
closed when a requirement is unmet — see
[Certification & Testing](/docs/connectors/certification-and-testing).

## Where to go next [#where-to-go-next]

* [Certification & Testing](/docs/connectors/certification-and-testing) — the scorecards that gate install and promotion.
* [Data Mapping](/docs/connectors/data-mapping) — why a changed mapper shows up as a deployment diff.
* [Policies, Quotas & Audit](/docs/connectors/policies-quotas-audit) — the egress, quota, and admission planes deployments run under.