Linear Release Setup
The
linear-release README is the source of truth for commands, flags, installation, environment variables, path filtering, and troubleshooting. Fetch it before generating any config — this skill focuses on the interactive setup workflow and the pipeline modeling decisions the README cannot make for the user.
Interactive Workflow
Step 1: Preflight
Before generating config, confirm:
- Pipeline exists in Linear — the user must have created a release pipeline in Linear first (Settings → Releases). Each pipeline has its own access key.
- Detect CI platform — look for (GitHub Actions), (GitLab CI), (CircleCI), or other CI config.
- Detect default branch — check
git symbolic-ref refs/remotes/origin/HEAD
Step 2: Map pipelines, then ask
Start by listing every build the user ships independently — each becomes its own Linear pipeline. Pipeline-vs-stage confusion is the single most common setup mistake, so whenever a split isn't obvious, apply the test in "Stages vs Pipelines" below.
Ask, in order:
-
CI platform — if not auto-detected.
-
What do you ship, and to whom? Prompt explicitly about common split candidates: production vs. beta or TestFlight, nightly or dogfood builds, staging, per-platform builds (iOS, Android, web), per-service in a monorepo. For each candidate, apply the test: can these hold different commits at the same time? Yes → separate pipelines. No (same immutable build moving through gates) → one pipeline with stages.
-
For each pipeline: continuous or scheduled?
- Continuous — every deploy completes a release. Typical for nightlies, dogfood, and web apps that ship on merge.
- Scheduled — releases collect changes over time and move through stages before shipping. Typical for versioned mobile and on-prem.
-
For each scheduled pipeline, ask explicitly:
- Branch model — just , or + release branches ()?
- Version source — calendar (), semver (), or commit SHA? Derived from branch name, CI variable, file, or git tag?
- Stages — what phases does a release move through before completion (e.g. "code freeze", "in qa")? Stages are gates on one build, not separate pipelines.
- Automation — all manual via , or automated (e.g. cutting a release branch auto-promotes it)?
-
Monorepo paths — if multiple pipelines share one repo, note which paths belong to each and wire up path filters in Linear pipeline settings or via
.
Step 3: Generate the CI configuration
Fetch the
README first for the current commands, flags, install snippet, and command-targeting rules. For GitHub Actions, prefer the official action (
linear/linear-release-action@v0
); for other platforms, use the CLI binary per the README's Installation section.
Pick the matching example template, adapt it (branch patterns, stage names, paths, version format), and add it to an existing workflow or create a new one. Multiple pipelines mean multiple workflows or jobs, each calling the CLI with its own access key — one secret per pipeline (e.g.
,
).
Each scheduled example includes a monorepo note in the header explaining how to split workflows for path filtering per platform.
Step 4: Remind about secrets
Tell the user to add the
secret to their CI environment:
- GitHub Actions: Repository Settings → Secrets and variables → Actions → New repository secret
- GitLab CI: Settings → CI/CD → Variables
- CircleCI: Project Settings → Environment Variables
The access key is created in Linear from the pipeline's settings page. Each pipeline has its own access key.
Key Concepts
A Linear release pipeline is one independent stream of releases, with its own version history, current release, and access key. This is not a CI pipeline; it is the unit Linear uses to track releases, and your CI config calls the CLI to update it. Different products, environments, or distribution channels that ship independently are different pipelines.
Pipelines come in two types —
continuous and
scheduled. See the README's
Pipeline Types section for the canonical description of each.
Stages vs Pipelines
A pipeline is one stream of releases. A stage is one phase inside a release on that pipeline. Confusing the two is the single most common setup mistake — work through the test below before writing any config.
The test: can two things be in-flight at the same time, holding different commits?
- Yes → separate pipelines. TestFlight running on while production ships 1.2 from a release branch. Web staging auto-deploying from while prod lags behind. A hotfix landing in one stream but not the other.
- No, it's the same build moving through gates → one pipeline with stages. A release is cut at 1.2, goes through code freeze, QA, and RC soak, then ships. The build never changes; only the phase does.
Stages are process gates: "code freeze", "in qa", "in review", "rc soak". They only exist on scheduled pipelines.
Ambiguous cases — apply the test:
- Beta / TestFlight. TestFlight soak before GA on the same build → stage on the production pipeline. A separate nightly or dogfood channel shipping distinct builds → its own pipeline.
- Staging. Staging that auto-deploys from (or runs hotfixes prod doesn't have) → separate pipeline. Staging that holds the exact same build as prod, just earlier in the promotion path → stage.
- Per-service monorepo. Each service that ships independently → its own pipeline, scoped by path filters. Unambiguous; services are never stages.
Stages can also be
frozen in Linear. A frozen stage makes
(without
) skip that release and land commits on the next one — a safety net for code freezes. This is a process tool, not a way to squeeze two pipelines into one.
Reference
Everything about commands, flags, environment variables, command targeting, path filtering, JSON output, and troubleshooting lives in the
linear-release README. For GitHub Action inputs and how they map to CLI flags, see the
action README. Always fetch these rather than relying on memory — they move ahead of this skill.
Checklist