> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parable.work/llms.txt
> Use this file to discover all available pages before exploring further.

# Provider Plugin Primer

> Learn how Provider Plugins turn external systems into governed data in the Provider Pool.

A Provider Plugin teaches Parable how to retrieve or receive data from a
Provider and turn it into governed tables in the Provider Pool. It owns the
repeatable integration contract; each Workspace supplies its own credentials,
configuration, and enabled data streams.

```mermaid theme={null}
flowchart LR
  P["Provider"] --> PP["Provider Plugin"]
  PP --> C["Workspace connection"]
  C --> S["Data streams"]
  S --> D["Provider Pool"]
```

## The parts of a Provider integration

| Product concept     | Technical name              | Responsibility                                                                       |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------ |
| Provider            | Vendor or source system     | The external product or system whose data a Workspace needs.                         |
| Provider Plugin     | Connector definition        | Shared authentication, transport, stream, traversal, limit, and schema rules.        |
| Provider connection | Connector instance          | One Workspace's selected strategy, credentials, ingestion configuration, and health. |
| Data stream         | Tap                         | One named record stream, such as issues, users, or events.                           |
| Provider Pool       | Provider catalog and tables | The SQL surface produced from synced records.                                        |

Keep these layers separate when writing or debugging a plugin. Changing a
definition changes the integration contract for every connection that uses it.
Changing a connection changes only one Workspace.

## Browse Provider Plugins

Each page in this section documents one installed Provider Plugin: what it
connects, the data streams it provides, setup, permissions, and troubleshooting.

The same page is rendered in Mintlify and loaded into the Provider connection
wizard. Its `##` sections become the app's Overview, Setup guide, Permissions,
and Troubleshooting tabs, so the documentation has one authored source. The
Permissions tab keeps its two disclosure levels in the app: expand a data
stream row to read what it enables and its scope, then expand a field row for
that field's developer identifier and interpretation.

## What every Provider Plugin must preserve

Regardless of transport, a plugin must establish:

* a stable Provider and plugin identity;
* an authentication or sender-verification boundary;
* named data streams with explicit record schemas;
* deterministic row identity and update ordering;
* bounded retry, concurrency, and rate-limit behavior; and
* a predictable projection into the
  [Provider Pool](/protocols/sql/data-catalog/provider-pool).

Workspace members configure connections and choose which supported streams to
enable. They do not rewrite a plugin's requests, pagination, traversal graph, or
schema contract.

Internal authors can implement another Plugin from the
[Custom Provider Plugins](/plugins/provider-plugins/custom-plugins) reference.

## Definition revisions and release

Creating a Provider Plugin gives it a stable connector identity in `draft` and
starts research. Research output and admin edits are candidate definition
versions; they do not change the active Plugin. An internal author reviews the
candidate diff, validation evidence, access requirements, and release scope
before activation.

Activation changes the definition used by new syncs. Syncs already in flight
keep their frozen definition. Catalog visibility, customer credential intake,
sync access, and deprecation are separate release controls and do not change
automatically when a definition activates or reaches another maturity level.

Internal authors use [Validate and release](/plugins/provider-plugins/custom-plugins/pull/validate-and-release)
for the evidence and release path. The underlying version and lifecycle
decisions are [EDR-0082](/edrs/0082-connector-entity-versioning-and-pool-pinning)
and [EDR-0089](/edrs/0089-revision-scoped-connector-lifecycle).