Drive work from your JIRA board: pick an id, get a reviewed PR

Your JIRA board is where the work actually lives — the tickets, the priorities, the thing you check to see what's left. But the bridge from a ticket to shipped code has always been manual: you read the issue, paste its text into a prompt, and let the agent vibe-code from a paragraph of prose that carries no contract and no acceptance criteria. When the code lands, nothing links it back; the ticket has no idea it was built. SpecShip's JIRA integration closes that gap. It's the first outbound integration we've shipped — and it lets a solo dev drive work straight from the board without leaving SpecShip or the terminal.

The shape of it is one loop: pick an id, get a reviewed PR, and the board stays in sync. It's local-first and secret-safe by construction — your token never leaves your machine and never lands in a commit, a comment, or the graph.

Connect once, and locally

You wire it up with specship jira configure. It saves your credentials to ~/.specship/jira.json — mode 0600, user-level, never inside the project, so there's nothing that can ride along into a commit. Both hosting models work: JIRA Cloud authenticates with your email plus an API token over HTTP basic; JIRA Data Center / Server uses a personal access token as a bearer. SpecShip infers which deployment you're on from the credentials you give it, or you can be explicit with --deployment.

# JIRA Cloud — email + API token
specship jira configure --base-url https://acme.atlassian.net --email you@acme.com --api-token <token>

# JIRA Data Center / Server — personal access token
specship jira configure --base-url https://jira.internal --pat <token>

# verify — prints "connected as <name>", never the token
specship jira test

specship jira test confirms the connection. It resolves who you are from the token and prints connected as <name> — the token itself is never echoed back. For headless or CI use, every setting has an environment override — SPECSHIP_JIRA_BASE_URL, SPECSHIP_JIRA_EMAIL, SPECSHIP_JIRA_API_TOKEN, SPECSHIP_JIRA_PAT, SPECSHIP_JIRA_DEPLOYMENT, and SPECSHIP_JIRA_CONFIG — so you can run it without a credentials file on disk at all.

The loop, in five tools

Once you're connected, the integration is agent-native: it's a set of MCP tools Claude Code calls, not a CLI you drive by hand. Five of them cover the whole path from board to PR.

• issues — lists the issues assigned to you. Your identity is resolved from your token, so you never type your name; an optional project filter narrows it down.
• issue — fetches a single issue by its key, so you can read it in full before committing to it.
• pick — fetches an issue and authors a well-formed SpecShip spec from it under specs/. It's idempotent and records the issue key, so picking the same ticket twice doesn't fork it.
• start — runs the bundled spec-implement workflow on that spec, pausing at its plan/approve gate before any code is written.
• track — a read-only table that joins each picked issue's SpecShip work-state with a live JIRA status read, so one glance tells you where everything actually stands.

# what's assigned to me? (resolved from my token)
specship_jira_issues

# turn PROJ-142 into a SpecShip spec under specs/
specship_jira_pick PROJ-142

# implement it — pauses at the plan gate, raises a PR when tests pass
specship_jira_start PROJ-142

# where does every picked issue stand? (live JIRA status)
specship_jira_track

A ticket becomes a real spec, not a prompt

The heart of this is pick. A JIRA issue is raw text; a SpecShip spec is a contract. pick does the translation: the issue's summary becomes the spec title, its description becomes the body, and its subtasks become acceptance criteria. What you get out is a well-formed spec that indexes into the graph like any other — with a body you can review, acceptance criteria you can check independently, and a link back to the exact code that satisfies it once it's built.

That's the whole point of routing the ticket through a spec instead of straight into the agent. The board stays the source of truth for what to work on; the spec becomes the durable record of what was actually promised — and because it's a real spec node, it earns everything the graph gives every other spec: a reviewable body, checkable criteria, and a link to its code that goes to drifted the day that code moves out from under it.

A PR only when the tests pass

start hands the spec to the bundled spec-implement workflow, which plans, pauses at its approval gate, implements, and verifies. The gate matters: nothing is written until you've seen the plan. And the finish line is strict — once the plan is approved and the implementation completes and its tests pass, SpecShip raises a pull request through the gh CLI. The issue key rides the branch name, the PR title, and the PR body, so JIRA's development panel links the PR straight back to the ticket with no manual cross-referencing.

The failure paths are honest, too. If gh is missing or unauthenticated, or the push itself fails, SpecShip tells you exactly why and leaves the branch and worktree intact so you can open the PR by hand — it never silently swallows finished work.

The board stays in sync — gracefully

Driving from the board is only half the value; the board also has to reflect what you're doing. SpecShip writes status back at two moments. On start, it assigns the issue to you and transitions it toward In Progress. When the PR is raised, it transitions the issue toward In Review and comments the PR link onto the ticket. Both transition names are configurable — set them in ~/.specship/jira.json, or via SPECSHIP_JIRA_TRANSITION_IN_PROGRESS and SPECSHIP_JIRA_TRANSITION_IN_REVIEW (they default to "In Progress" and "In Review").

The key word is gracefully. Every JIRA workflow is different, and a transition you name might not exist in a given project. When that happens SpecShip doesn't error out — on the PR side it still comments the link and simply reports that it skipped the transition. And a JIRA hiccup on start never blocks your local work; the implementation runs regardless of whether the board write succeeded. What it will never do is mark an issue Done or close it — that transition is yours alone. track is where you watch it all come together: your local spec state and the live JIRA status, side by side.

Secret-safe by construction

An integration that holds a credential has to be paranoid about it, and this one is. The token is never logged, printed, or echoed into any output, error message, JIRA comment, or the graph — the closest you ever get to seeing it is connected as <name>. Every request is host-locked to the base URL you configured and refuses to follow a redirect to a different host, so a misconfigured or hostile server can't bounce your token somewhere it shouldn't go. Combined with the user-level 0600 credentials file that lives outside the project, there's no path by which your token ends up in a commit, a shared graph, or a PR body.

What it deliberately doesn't do

This is a solo-dev loop, and it's scoped like one on purpose. There are no team or sprint features — no board automation, no bulk import. It works one issue at a time: pick it, build it, ship the PR, move on. And the two decisions that are genuinely irreversible stay with you — SpecShip never marks an issue Done and never merges the PR. It gets you from a ticket id to a reviewed, linked, test-passing pull request with the board already updated around it. The last word is still yours.