Integrations
Integrations connect a Stib board to an external source of work. A provider connection is owned either by the server, where every project shares it, or by a single project, where it is visible and usable only there. Create the connection at the right scope, then attach it and a mapping to the appropriate board.
Providers
The current integration layer includes:
| Provider | Source |
|---|---|
| GitHub | Issues and pull requests |
| Azure DevOps | Work items |
| Jira | Issues and epics |
| Linear | Issues and projects |
| Plane | Issues, per-workspace, with per-person tokens |
| BMAD | Local BMAD artifacts; no remote credential |
| Custom | REST API described manually or imported from OpenAPI |
Availability can depend on the licence plan and server configuration. The per-provider plan rule is the same whichever scope owns the connection; after a downgrade, background polling stops for the providers the plan no longer covers.
Configuration flow
Server connection
Shared by every project; requires server administration privileges.
- Open Settings → Server → Integrations and create a provider connection.
- Enter the provider-specific endpoint/account and the narrowest credential possible.
- Test the connection.
A server connection does not pin a remote target: each board attached to it chooses its own.
Project connection
Owned by one project and invisible to the others; requires a project admin (project owner or admin, organization admin, or global admin). Its events are recorded in the project's History.
- Open Project settings → Integrations and create a provider connection. Server connections are listed there too, read-only, under Server connections; they are configured in the server settings.
- Enter the endpoint/account and credential, then test the connection, as for a server connection.
- Choose the remote target (repository, project, team, workspace, filter, depending on the provider). It is pinned on the connection. BMAD works on local artifacts and skips this step.
Changing a pinned target later only affects boards attached afterwards: a board already attached keeps the target it was attached with, since its imported cards reference items of that container. To move an existing board, detach it and attach it again.
Board attachment
- Open the target board's integration settings and select a connection.
- With a server connection, select the external container (repository, project, workspace, etc.). With a project connection, the board inherits the pinned target, shown read-only, and this step disappears.
- Map external states/fields to Stib columns and fields.
- Choose manual or automatic import behavior, then preview before enabling sync.
An integration definition can exist without being attached to every board.
The three axes of a column mapping
Each mapped column carries three independent settings. They are easy to confuse, and confusing them is the usual cause of "nothing happens":
| Axis | Values | The question it answers |
|---|---|---|
| Import | None / Manual / Auto | does a provider item become a card? |
| Export | None / Manual / Auto | does a card born here become a provider item? |
| Sync | None / Inbound / Outbound / Bidirectional | does an already paired card follow, and which way? |
The first two decide a birth, the third a follow-up, and none is deducible from the others. A column can legitimately create in both directions while propagating moves only towards the provider — one-way on moves, two-way on creation.
Export defaults to None, so an existing board keeps exactly the behaviour it had. Set it to Auto and every card created in that column opens an item in the provider; set it to Manual and the card menu offers Create in the provider instead. Auto keeps that menu entry too: it is the way back for a card whose creation failed, or one that predates the setting.
Once a card and an item are paired — whether the card was imported or exported — the Sync axis governs everything that follows: moves, title, description, labels, priority.
Not every provider can create. BMAD never does, and a custom REST provider only does once you configure a creation endpoint. A provider that cannot create simply ignores the setting.
Received and sent statuses
A column receives any number of provider statuses and sends at most one. When an item reaches a status the column receives, its card comes into the column (if the column's sync is Inbound or Bidirectional), and import offers items at any of those statuses. Dropping a card in the column writes the status it sends, and an item created from the column is born at that status.
A status is received by one column only — otherwise nothing would say where the card goes — but several columns may send the same status. A finished ticket can therefore land in your last column even though that column keeps writing its own status: have "Released" receive Released, Closed and Validated in production, and send Released.
Following moves inbound or importing automatically needs a received status; pushing moves or creating items needs a sent status. Saving is refused otherwise, with the reason under the row.
Statuses without a column, under the mapping table, lists the provider statuses carried by this board's cards that no column receives or sends, with how many cards carry each and where they sit. Those cards stay where they are; give the status to a column to place them.
A card you move by hand waits for the provider to report the status it sent. Until then — at most a few minutes — an older status coming back from a poll or a webhook does not pull the card back.
Import and synchronization
Imported cards keep an external identifier and link. Stib tracks sync state and reports conflicts or unsupported operations. Decide which side owns each mapped field; a bidirectional workflow without a clear source of truth can oscillate or overwrite user intent.
Webhooks can accelerate inbound updates, while scheduled/manual sync reconciles missed events. Outbound changes depend on provider capability and mapping.
Custom REST providers
A custom provider can define base URL, authentication, endpoints, pagination, list/detail shapes, field paths, and state mappings. Creating items outbound takes one more endpoint: a creation URL, its method, and a body template where carries a configured variable and {title} / {description} / {status} carry the card. The response is read back through the same field mappings as the detail endpoint, so it must return the created item — Stib needs its identifier to pair the card. Supported authentication includes an API-key header, Basic, explicit headers/query parameters, and an OAuth-shaped Bearer option. The latter currently sends the saved client secret directly as a Bearer token; Stib does not perform a full OAuth 2.0 token exchange for custom providers yet.
Use the test-and-preview step against non-destructive endpoints before saving. An imported OpenAPI description is a starting point; verify operation, pagination, and field mappings manually.
Network security
Stib blocks loopback/private integration targets by default to reduce SSRF risk. STIB_ALLOW_PRIVATE_URLS=1 broadens access for an intentional LAN deployment and should not be enabled on a multi-tenant or internet-exposed server without additional network controls. That switch applies to server connections only: a project connection always stays on public hosts, whatever the environment says, because a project admin never made that deployment choice.
Store provider secrets in the integration form, not in mapping templates. Only a server administrator stores a secret on a server connection; on a project connection, only a project admin can create, edit, delete, test or introspect it. Editors and contributors attach boards and browse remote projects and statuses; readers only see the connection in the list. Custom headers are encrypted and their saved values are hidden. Rotate a provider secret through the supported edit flow and retest the connection.
Troubleshooting
Check connection test, integration status, board mapping, server logs, audit events, provider permissions/rate limits, webhook delivery, and the server's DNS/network view. A URL reachable from the desktop client may still be unreachable from the server container.
Next: Pipeline and Automation and Audit & Collaboration.