Connecting Sources

Architecture that drifts from reality is worse than no architecture at all. Sources are how you anchor a board to actual code and docs, so what you're looking at stays true as the systems move.

This is the how-to. For the full catalog of what you can connect, and the rules about how many governing sources a board can carry, see the Sources Overview.

Before you start

Sources live in a workspace-level catalog: you register one once, then bind it to every board that needs it. You'll need contributor access or above, and — for a connector source like Confluence, Notion or Jira — the provider authorized for your org first.

A binding carries a role. Governing means the source shapes the board; reference means it's context chat and insights can read without ever redrawing anything. How many governing sources you get, and the one exclusive slot for a Code Plugin source, are both in the Sources Overview.

Register a source

You reach the catalog from a board, not from the nav. Open the board's hub, find the Bindings card, and choose Add — the catalog picker opens, and Add Source inside it opens the menu of everything you can register.

What you fill in depends on what you picked:

• Note — paste the markdown or text, and give it a title.
• Web URL — paste the address, and give it a title you'll recognise later.
• Code Plugin — name the source; the API secret is generated when you save it.
• A connector — pick the provider, then browse your authorized account and select the pages, spaces or issues you want. See Provider Sources.

Registering is not binding. A source in the catalog does nothing until a board binds it.

Bind it to a board

From the same Bindings card, Bind Governing Source starts a governing bind and Add starts either kind. The dialog has two sides, and picking one is the whole decision:

• Govern this board — this source shapes the graph, participates in sync, and can conflict with another governing source. The button reads Bind as governing source.
• Attach reference context — this source is read-only context. The button reads Attach reference source.

Expand

Bind a governing Code Plugin source to a board that doesn't have one and something else happens: the board becomes an app board, and it tells you so. That's the same act as the Make this an app control in the board's rail — two doors, one result. App Boards & Hubs covers what turns on.

The credentials you get once

The moment a governing Code Plugin bind completes, a Plugin credentials — copy now dialog opens by itself. It carries the binding token, the API secret, the board slug and the branch, rendered as ready-to-paste snippets — including the PMAP_BINDING_TOKEN, PMAP_API_SECRET, PMAP_BOARD_SLUG, PMAP_BRANCH and PMAP_BASE_URL environment variables — each with its own copy button.

Copy them then. The amber warning on that dialog is literal: the live secret leaves our servers at exactly two moments, and this is one of them. Ask for the binding's credentials afterwards and you get ck_cp_live_****.

Expand

Missed it? The other moment is Regenerate secret & copy, on the binding's row. It mints a fresh secret and kills the old one immediately, so anything still holding the old one stops working until you update it. The full credential reference lives in The Code Plugin, and the wire format in the Boards API.

Sources that come from a connector

A connector source takes one extra step, once. Open Settings → Connectors, find the provider, and authorize it — you'll go through the provider's own OAuth screen and land back in the portal. That's org-level and one-time; from then on anyone with the right access can browse it.

After that it's the normal flow: Add Source → Import from a connector → your provider, then browse and select. Authorizing on its own pulls nothing — nothing reaches a board until you add items as sources. Provider Sources covers browsing and bulk-adding.

When a binding breaks

Bindings break in a small number of ways, and the board's hub is where you see it. Each binding shows its pulse — how recently anything arrived — and its sync state, so a source that quietly stopped reporting looks different from one that's failing loudly. Sources Overview has what each signal means.

What's next