Jira Sync plugin
@slaw/plugin-jira-sync mirrors a Jira board into a SLAW squad in both directions, and illustrates how plugins use managed agents and routines for board-visible, operator-controlled automation.
The plugin is included in the SLAW repository as a first-party worked example. Its id is slaw.jira-sync.
Jira Sync isn't a background connector — it ships a real managed agent (jira-sync-agent) that appears in your squad's org chart. It mirrors the Jira board both ways, and when a sync fails the routine files a board-visible issue and assigns it to that agent to investigate. The integration is a member of the squad, not a hidden job, so every action stays visible and operator-controlled.
- SLAW running locally (see Quickstart).
- A Jira site with a board you can connect. You will need the board id, your Atlassian account email, and a Jira API token.
How sync works
Jira → SLAW: The plugin receives Jira issue events via a webhook (POST /api/plugins/<pluginId>/webhooks/jira-event). New Jira issues become SLAW issues stamped with originKind = plugin:slaw.jira-sync:issue and originId = <JIRA-KEY>. Deduplication is keyed on the Jira issue key, so an issue is never created twice. An hourly full-sync job (0 * * * *) reconciles any issues the webhook missed.
SLAW → Jira: When a mirrored issue reaches done or cancelled, the plugin posts a summary comment to the Jira issue and closes it. Set syncStatusBack: true in the instance config to also push intermediate status changes back to Jira.
Managed resources
The plugin declares two managed resources in its manifest:
| Resource | Key | Default state |
|---|---|---|
| Managed agent | jira-sync-agent | Paused, zero budget |
| Managed routine | jira-full-sync | Paused, schedule disabled |
Both start in a paused state so the operator deliberately opts in after installation. The managed agent appears in the squad org chart; the managed routine creates board-visible issues each time it runs.
Install and configure
1. Store the Jira API token
npx slaw secrets set JIRA_API_TOKEN
SLAW stores the token encrypted. You will reference the secret name (JIRA_API_TOKEN) in the plugin config — never the value.
2. Install the plugin
npx slaw plugin install @slaw/plugin-jira-sync
3. Configure the instance
From the SLAW UI, open Settings → Plugins → Jira Sync and fill in the instance config:
| Field | Required | Description |
|---|---|---|
jiraUrl | yes | Base URL of the Jira site, e.g. https://acme.atlassian.net |
jiraBoardId | yes | Numeric board id |
jiraUsername | yes | Atlassian account email (used for Basic auth) |
jiraApiTokenRef | yes | Name of the SLAW secret holding the API token (e.g. JIRA_API_TOKEN) |
targetSquadId | yes | Id of the SLAW squad that mirrored issues are created in |
targetProjectId | no | SLAW project for mirrored issues |
targetAssigneeAgentId | no | Agent assigned to mirrored issues; unassigned if omitted |
syncStatusBack | no | Push all status changes back to Jira (default: completion only) |
4. Register the webhook in Jira
Register the plugin webhook URL in your Jira site under Settings → System → Webhooks:
POST https://<your-slaw-host>/api/plugins/slaw.jira-sync/webhooks/jira-event
Select Issue Created and Issue Updated events.
The exact webhook path includes the plugin instance id as installed; confirm the URL matches npx slaw plugin inspect slaw.jira-sync output before registering in Jira.
5. Enable the managed resources
After configuration, enable the managed agent and routine so the operator has opted in:
- In the squad org chart, find Jira Sync Agent and set its status to active.
- Open Routines and enable the Reconcile Jira board routine schedule.
The routine creates a board-visible issue each time it runs. The managed agent is assigned to those issues and is responsible for investigating any sync failures the plugin reports.
Verify
npx slaw plugin inspect slaw.jira-sync
A healthy install shows status: ready. If the plugin reports errors, the lastError field has the detail.
Trigger a manual full-sync via the routine UI or by creating a Jira issue and confirming it appears in the SLAW squad within a few seconds of the webhook firing.
Error handling
| Jira API error | Plugin behaviour |
|---|---|
| 401 / 403 | Surfaces to the operator via activity log; does not retry |
| 404 on a Jira transition | Notes the missing transition on the SLAW issue; moves on |
| 429 rate limit | Backs off; the next hourly full-sync reconciles missed issues |
Next steps
- Plugins overview — the managed resource pattern and capability model
- Writing a plugin — build your own connector using the same patterns