Integrations
Integrations connect a Stib board to an external source of work. Configure provider credentials at server scope, then attach an integration and 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 |
| 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.
Configuration flow
- Open Settings → Server → Integrations and create a provider connection.
- Enter the provider-specific endpoint/account and the narrowest credential possible.
- Test the connection.
- Open the target board's integration settings.
- Select the external container (repository, project, workspace, etc.).
- 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.
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. 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.
Store provider secrets in the integration form, not in mapping templates. 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.