Linear integration

Linear — wired into the lifecycle

Stop manually creating Linear issues. fastpace's hook-driven event bus creates Projects, parent Issues, and child Issues in your Linear team the moment you author a PRD, ERD, or plan — and a 15-minute reconciler keeps state in sync via GraphQL.

Setup in 4 steps → See the hooks Compare with Jira →
Hook-driven 3-level hierarchy GraphQL native No webhooks needed Estimate auto-mapped
Why this matters

An integration that keeps Linear honest

Most Linear integrations are manual sync buttons. This one is an event bus — every artifact your team produces fires a hook, and the right thing happens in Linear without anyone clicking.

Projects + Issues, in sync

Every PRD becomes a Linear Project. Every ERD epic becomes a parent Issue. Every story becomes a child Issue with proper estimation. Auto-created on file write.

Drift surfaces in 15 minutes

Manually moved an issue's state in Linear? Reassigned someone? The reconciler catches it via GraphQL and surfaces the divergence in your local dashboard.

Audit trail by default

Every push, every state transition, every drift lands in fastpace/audit.log. Linear becomes one provider on a hooks-driven event bus, not a black-box export.

GraphQL-native, fast

No webhooks required, no public endpoint. fastpace pushes mutations on hook fire, polls Linear's GraphQL every 15 minutes. Local-first, async + retry.

Hierarchy mapping

Linear's Project + parent/child Issues

Linear has no native "Initiative" type, so fastpace models the 3-level hierarchy as Project (initiative) → parent Issue (epic) → child Issue (story). Same shape as Jira; native to Linear.

fastpace artifact
fastpace/docs/prd/[slug].md
fastpace/docs/erd/[slug].md
fastpace/exec-plans/[slug].json (epics)
fastpace/exec-plans/[slug].json (stories)
fastpace/watch-cards/[slug].json
Linear object
Project teamIds = [team_id]
comment on first issue link to ERD
Issue projectId = parent
Issue parentId = epic, estimate auto-mapped
issueUpdate(stateId) via GraphQL
Lifecycle hooks

Eight events. Each one is a GraphQL mutation.

fastpace's hooks call into api.linear.app/graphql with a single auth header. Toggle individual hooks via fastpace.config.yaml.

Event
Fires when
Linear GraphQL call
prd.written
a /fp-write-prd command writes the PRD
projectCreate mutation · description=PRD body
erd.written
/fp-prd-to-erd writes the engineering design
commentCreate on the project's first issue with ERD link
execplan.written
/fp-erd-to-execplan generates the plan
issueCreate ×N for parent epics, ×M children with parentId set
adr.written
/fp-write-adr lands a numbered decision
fan-out comment to every linked Project
phase.changed
a watch card transitions phases
projectUpdate or issueUpdate with stateId from team workflow
pr.opened
a PR is opened
comment on the active Issue with PR URL
pr.merged
a PR merges
comment merge confirmation on the project
review.completed
/fp-review-pr produces findings
commentCreate with structured findings
Phase → Linear state

Watch-card phases drive Linear workflow states

When a watch card moves phase, fastpace looks up the matching workflowState by name from your team's configured states and posts an issueUpdate(stateId) mutation.

phase
planning
↓
linear state
In Definition
phase
spec
↓
linear state
In Design
phase
write-tests
↓
linear state
In Progress
phase
implement
↓
linear state
In Progress
phase
run-tests
↓
linear state
In Review
phase
document
↓
linear state
In Review
phase
create-pr
↓
linear state
In Review
phase
push
↓
linear state
Done
Drift detection

GraphQL-driven reconciliation

Every 15 minutes, the poller queries each linked Project via a GraphQL query that fetches Project state + all child issues. fastpace normalizes the response and compares to its expected state. Divergences show up in the local dashboard with a "Mark resolved" action.

Partial refunds FP-100 linear
Phasespec
Statecompleted
Issues0 / 5
Pulled2m ago
Drift detected: fastpace expects In Design · Linear has completed
Setup

Four steps to live

1

Configure Linear in fastpace

Edit fastpace.config.yaml. The team_id is a UUID — easiest to grab via fastpace integrations test after step 3.

integrations:
  provider: linear
  hierarchy: initiative-epic-story
  linear:
    team_id: 11111111-2222-3333-...
    team_key: ENG          # cached for display
2

Create a Linear API key

Go to linear.app → Settings → API, create a personal API key, and save it to fastpace/.integrations.local.json (auto-gitignored, chmod 0600):

{
  "linear_api_key": "lin_api_..."
}
3

Verify the connection

$ fastpace integrations test
✓ Connection ok. authenticated as Jordan Park
  team: Engineering (ENG)
  teams visible: 4

If you don't have team_id yet, the test output lists your visible teams — copy the UUID into the config.

4

Author your first feature

Run /fp-write-prd in Claude Code. The PRD write fires prd.written → a Project is created in Linear automatically.

$ fastpace integrations list
  ✓  partial-refunds            FP-100      phase=planning
  !  legacy-cleanup             FP-87       1 drift  phase=spec
CLI commands

For when you want to run Linear sync manually

fastpace sync [slug]

Re-runs artifact-write events. Without a slug, syncs every linked feature in your repo.

--push push only --pull reconcile only
fastpace integrations status

Shows team_id, hierarchy, hook on/off matrix, and whether your API key is configured.

fastpace integrations test

Hits Linear's viewer { id name email } query to verify auth + lists visible teams.

fastpace integrations list

Roll-up of every linked feature × Project identifier × phase × drift count.

Ready to wire Linear into your lifecycle?

Test-drive in a sandbox first; then edit one config block, paste one API key. The hooks do the rest.

Test-drive fastpace → Compare with Jira Back to home