Jira Sync plugin
@slaw-ai/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-ai/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-ai/slaw plugin install @slaw-ai/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) |
webhookSecretRef | no | Name of a SLAW secret holding the Jira webhook signing secret. When set, inbound deliveries must carry a valid X-Hub-Signature or they are rejected. |
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.
Verify webhook deliveries (recommended)
By default the endpoint accepts any well-formed delivery. To ensure only Jira can drive sync, set a webhook secret so deliveries are authenticated:
- In Jira's webhook settings, set a secret. Jira signs each delivery with HMAC-SHA256 and sends it in the
X-Hub-Signatureheader (sha256=<hex>, over the raw body). - Store that same secret as a SLAW secret (e.g.
JIRA_WEBHOOK_SECRET). - Set the plugin instance's
webhookSecretRefto that secret's name.
Once configured, deliveries without a valid signature are rejected before any work is done — a forged or unsigned POST to the endpoint cannot create issues.
The exact webhook path includes the plugin instance id as installed; confirm the URL matches npx @slaw-ai/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-ai/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