How do Linear Cycles relate to weekly changelogs?

Cycles provide natural sprint boundaries. Filtering issues where `cycle.number = current` and `state.type = completed` yields an exact record of what shipped during that cycle.

What happens if an issue is completed outside an active cycle?

Rely on the `completedAt` timestamp rather than cycle membership alone. This ensures out-of-cycle hotfixes and ad-hoc bug resolutions are never omitted.

How do Linear labels map to changelog categories?

Labels like `improvement`, `feature`, and `fix` map directly to standard changelog sections. Custom team labels like `dx` or `perf` can be assigned to technical highlights.

Does Linear support real-time webhooks for completed issues?

Yes. Linear webhooks emit `Issue` update events with an `action: update`. When `data.state.type` changes to `completed`, the event is indexed immediately.

Turn Linear Cycles and Completed Issues into a Clean Changelog

Linear cycles map directly to weekly changelogs when you query by completedAt timestamps and project milestones. Here is the automated workflow.

Soobrief Team — Product & Engineering, Sooapps · 2026-08-18

In short

A production-grade Linear changelog is built by filtering issues with `completedAt` inside the release window, mapping Linear Teams to product surfaces, and grouping by issue labels. Once these deterministic rules are applied, cycle reviews transform into instant customer-facing release notes.

A production-grade Linear changelog is built by filtering issues with completedAt inside the release window, mapping Linear Teams to product surfaces, and grouping by issue labels. Once these deterministic rules are applied, cycle reviews transform into instant customer-facing release notes.

Linear is loved by high-velocity software teams for its keyboard-driven UI and cycle mechanics. Yet at the end of a cycle, product managers still spend hours reading through closed issues, trying to figure out which technical commits correspond to meaningful user improvements.

1. Cycle Filtering vs Timestamp Filtering

Linear organizes work into Cycles (typically 1 or 2 weeks). While cycles represent intent, real-world releases often span cycle boundaries due to hotfixes or mid-week deployments.

The most robust extraction strategy uses a dual filter:


query CompletedIssues($teamId: String!, $since: DateTime!) {
  issues(
    filter: {
      team: { id: { eq: $teamId } }
      completedAt: { gte: $since }
      state: { type: { eq: "completed" } }
    }
  ) {
    nodes {
      id
      title
      completedAt
      project { name }
      labels { nodes { name } }
      cycle { number }
    }
  }
}

Property	Linear GraphQL Type	Role in Changelog
Completion Signal	`state.type == "completed"`	Captures resolved tickets regardless of custom workflow status name.
Time Anchor	`completedAt`	Provides ISO-8601 UTC timestamp for chronological sorting and deduplication.
Product Area	`project.name` or `team.name`	Establishes top-level category (e.g. "Desktop App", "Billing API").

2. Converting Linear Labels into Readable Sections

Linear issues carry rich label metadata. Using deterministic categorization avoids arbitrary LLM sorting:

feature / user-facing → New Features: Highlighted at the top of the update.
fix / bug → Improvements & Fixes: Grouped into concise outcome bullet points.
performance → Performance & Reliability: Showcases speed and optimization wins.
internal / chore → Internal & Infrastructure: Gated behind private or technical summary views.

3. Automation via Linear Webhooks

Linear's webhook system sends JSON payloads with signature verification via linear-signature. When an issue transition occurs, the payload includes the previous and current state:


{
  "action": "update",
  "type": "Issue",
  "data": {
    "id": "c7a8b9e1-...",
    "title": "Support dark mode syntax highlighting in editor",
    "completedAt": "2026-09-08T14:32:00.000Z",
    "state": { "name": "Done", "type": "completed" }
  },
  "updatedFrom": {
    "stateId": "in_progress_state_id"
  }
}

By recording these events continuously, your weekly changelog is always ready before the Friday sync.