@shipwrights/source-jira

Jira backlog source adapter for @shipwrights/core. Pulls issues via JQL, materialises them as epic files, writes status transitions and PR links back to Jira.

Quick start

npx @shipwrights/source-jira init           # one-time setup
npx @shipwrights/source-jira healthcheck    # verify connection
npx @shipwrights/source-jira ls             # list backlog items
npx @shipwrights/source-jira pick           # show the next item to work on

init walks you through eight prompts, verifies the connection against Jira, and writes:

| File | Purpose | |---|---| | .env.local | JIRA_HOST, JIRA_EMAIL, JIRA_API_TOKEN (gitignored) | | .shipwrights/jira.json | non-secret config (host, email, jql, pick_statuses, status_mapping, field mapping) | | .gitignore | adds .env.local and .shipwrights/ if missing |

Wizard steps:

1. Host — your Atlassian subdomain (e.g. myorg.atlassian.net)
2. Email — your Atlassian account email (pre-filled from git config user.email)
3. API token — paste a token from id.atlassian.com (input hidden)
4. Auth verify — connection is tested immediately; actionable error printed on failure
5. Project — pick from a live list of your projects
6. Sprint scope — active sprints, a specific sprint, or no sprint filter
7. Assignee scope — mine + unassigned, only mine, only unassigned, or anyone
8. Status columns — two sub-steps:
   • Pick-from columns (multi-select): which Jira statuses the orchestrator should pull items from. All statuses are listed grouped by category (To Do → In Progress → Done); everything outside the Done category is pre-selected. Enter space-separated numbers to change the selection.
   • Working column (single-select): which status items move to when the orchestrator starts working on them. Defaults to the first In Progress category status.
9. JQL confirm — the wizard shows the composed JQL (incorporating your status column choices) and lets you edit it before saving
10. Field detection — auto-detects Story Points and Epic Link custom field IDs

If something goes wrong (wrong subdomain, scoped token, etc.), the wizard prints a specific fix instead of just a raw HTTP status.

The other three commands read your written config and run the same primitives the orchestrator uses — healthcheck is source.healthcheck(), ls is source.listAvailable(), pick is source.pickNext(). Useful for sanity-checking your JQL or debugging field mappings.

Install (programmatic use)

npm install -D @shipwrights/core @shipwrights/source-jira
# or
pnpm add -D @shipwrights/core @shipwrights/source-jira

Configure manually

If you don't want the wizard, generate a Jira API token at https://id.atlassian.com/manage-profile/security/api-tokens, then set env vars:

export [email protected]
export JIRA_API_TOKEN=<your-token>

Reference them from .shipwrights.yml:

backlog:
  source:
    kind: jira
    config:
      host: myorg.atlassian.net
      email_env: JIRA_EMAIL
      token_env: JIRA_API_TOKEN
      jql: 'project = SHOP AND status in ("Ready for Dev", "Refined") ORDER BY priority ASC'
      # Optional: which statuses the orchestrator picks items from (informational;
      # the JQL above is the authoritative filter).
      pick_statuses:
        - "Ready for Dev"
        - "Refined"
      # Optional: transition the issue when the orchestrator starts working.
      status_mapping:
        sliced: "In Progress"
  state_dir: docs/backlog/epics

What this adapter implements

The BacklogSource contract from @shipwrights/core:

| Method | Behaviour | |---|---| | healthcheck() | Calls GET /myself to validate auth | | listAvailable() | Runs the configured JQL (POST /rest/api/3/search/jql) with cursor pagination | | pickNext() | listAvailable() sorted by priority + key | | materialize(item, dir) | Renders the Jira issue's description (ADF) to markdown + writes an epic file with frontmatter | | markStatus(id, status) | Transitions the Jira issue (3 statuses) or posts a comment (middle states) | | attachPR(id, prUrl) | Posts a comment with the PR url |

Status mapping

Most Shipwright lifecycle states are internal artefacts that don't have a useful Jira counterpart. The adapter only transitions the Jira issue for states that appear in status_mapping; everything else posts a comment.

Default mapping (no status_mapping configured):

| Shipwright status | Jira action | |---|---| | refined | Transition to Ready for Dev | | ready-for-human-review | Transition to In Review | | shipped | Transition to Done | | sliced, built, integrated, tested, reviewed | Post a comment, no transition |

When you run init and choose a working column, the wizard adds a sliced entry to the mapping so the orchestrator transitions the issue as soon as it starts working:

// .shipwrights/jira.json (written by init)
{
  "status_mapping": {
    "sliced": "In Progress"
  }
}

Override or extend the mapping manually in .shipwrights/jira.json or .shipwrights.yml:

config:
  status_mapping:
    sliced: "In Progress"
    refined: "In Progress"
    shipped: "Closed"

Field mapping

Standard fields (summary, priority, status, labels) are mapped by name. Story points and parent epic are custom fields — convention-detected by default, overridable:

config:
  field_mapping:
    size: customfield_10016     # Story Points
    parents: customfield_10014  # Epic Link

Status

v0.5.1 — sprint + assignee scoping in init, status column selection (pick-from columns + working column), currentUser / assignToCurrentUser, actionable healthcheck errors. End-to-end pilot-validated against a live Atlassian Cloud tenant.

Contributing

We welcome contributions. See CONTRIBUTING.md for how to set up, run tests, and open a PR. Security issues should be reported privately — see SECURITY.md. All participants follow the Code of Conduct.

License

MIT