Skip to content
Accelerator

Sync Work Items with Jira or Linear

This guide connects a repository to a remote tracker and keeps the work items in meta/work/ reconciled with it. Work items function fully offline — the tracker is optional — but once connected, changes flow in both directions.

Prerequisites

Section titled “Prerequisites”
  • jq installed (and sha256sum or shasum on the PATH).
  • A Jira Cloud API token (from id.atlassian.com) or a Linear personal API key (lin_api_…).

  1. Initialise the integration once per repository.

    Run init-jira:

    /accelerator:init-jira --site your-subdomain --email you@example.com

    It verifies your credentials and writes two kinds of state under .accelerator/state/integrations/jira/: per-developer files (gitignored) and team-shared catalogues (projects.json, fields.json, committed).

  2. Store credentials in the local config file. Tokens belong in .accelerator/config.local.md (gitignored), never the shared config — ideally via a command rather than a literal value:

    ---
    jira:
      token_cmd: "op read op://Private/jira/token"
    ---

    See the configuration cookbook for the full recipe including the team-shared side.

  3. Declare the active tracker. In the shared .accelerator/config.md:

    ---
    work:
      integration: jira
      id_pattern: "{project}-{number:04d}"
      default_project_code: "PROJ"
    ---

    Without work.integration, sync-work-items stops with an error telling you what to set.

  4. Preview before the first sync. Run sync-work-items with --preview to see every intended push, pull, and conflict with zero writes on either side:

    /accelerator:sync-work-items --preview

  5. Sync. The default mode is bidirectional:

    /accelerator:sync-work-items
    • Local items changed since the last sync are pushed; remote changes are pulled.
    • Remote issues with no local counterpart become new local work items with allocated IDs and an external_id.
    • Conflicts (both sides changed) prompt you to type remote, local, or skip per item.
    • Work items with local uncommitted edits are never overwritten.

    Use --push-only or --pull-only for one-directional syncs (they report conflicts without prompting), and --all to pull beyond the default project scope on Jira.

  6. Read the summary. The skill ends with an ID-by-ID summary — pushed, pulled, newly created, conflicts skipped — so nothing changes silently. Large operations (more than 25 pulls or creations) ask for confirmation first.

Day-to-day usage

Section titled “Day-to-day usage”

See also

Section titled “See also”