Skip to main content

SYNC LINEAR ISSUE STATES WITH GRAPHITE PR STACKS

This guide shows you how to find Linear issues whose state no longer matches their GitHub or Graphite pull requests. You review the planned changes in a dry run, then move each issue to the matching state with @mgreten/graphite-linear-sync.

Prerequisites

  • A Linear personal API key stored in a vault named linear under the key api-key (see Vaults)
  • Pull requests whose bodies reference Linear tickets, such as ENG-123
  • A local clone of the repository, which the behavior uses to detect Graphite stacks

Pull the extension

swamp extension pull @mgreten/graphite-linear-sync

You will see output like:

INF extension·pull: Pulling "@hivemq/linear"@"2026.03.30.14"
INF extension·pull: Identity verified: "@hivemq/linear"@"2026.03.30.14"
INF extension·pull: Pulled "@hivemq/linear"@"2026.03.30.14"
INF extension·pull: Extracted 6 files:

Set up the behavior

Create a behavior named pr-sync of type @mgreten/graphite-linear-sync (see Create and Run a Behavior). All four global arguments are required:

globalArguments:
  apiKey: "${{ vault.get('linear', 'api-key') }}"
  teamKeys:
    - ENG
  repo: myorg/my-repo
  repoPath: /home/user/repos/my-repo

The behavior uses teamKeys to recognise ticket IDs in PR bodies, so list every team whose tickets your PRs reference. Set repo to the GitHub owner/repo and repoPath to the local clone.

Scan the stack

To check one Graphite stack, including PRs merged recently, pass the stack's branch:

swamp behavior run pr-sync scan_stack \
  --input branch=feature/checkout-redesign \
  --input 'includeRecent:json=true'

This command scans the open PRs on that stack for Linear ticket references and compares each PR's merge status with the state of its Linear issue. It writes the result as a scan_result resource that groups PRs by Linear issue.

To scan all open PRs in the repository instead of one stack, leave out branch.

Preview the transitions

swamp behavior run pr-sync true_up --input 'dryRun:json=true'

This command reads the latest scan_result and writes a true_up_result resource listing the transitions it would make. It doesn't change any Linear issue.

Check the listed transitions before going further. If the list includes an issue that should stay as it is, fix the reference in the PR body and run scan_stack again.

Apply the transitions

swamp behavior run pr-sync true_up --input 'dryRun:json=false'

This command moves each Linear issue whose state differs from its PRs to the matching state and records what it changed in a true_up_result resource. Issues that already match are left unchanged.

true_up always reads the latest scan_result. If PRs have merged since the last scan, run scan_stack again before applying.

To run the scan and the update in order, put both in a workflow (see Create and Run a Workflow). To require a review before issues change, add an approval step between them (see Gate a Workflow with Manual Approval).