linear-release-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linear Release Setup

Linear Release 配置设置

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.

linear-release README是命令、参数、安装步骤、环境变量、路径过滤及故障排查的权威来源。生成任何配置前请先查阅该文档——本技能专注于交互式配置流程，以及README无法为用户做出的流水线建模决策。

Interactive Workflow

交互式流程

Step 1: Preflight

步骤1：预检

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/workflows/*.yml
```
(GitHub Actions),
```
.gitlab-ci.yml
```
(GitLab CI),
```
.circleci/config.yml
```
(CircleCI), or other CI config.
Detect default branch — check
```
git symbolic-ref refs/remotes/origin/HEAD
```
or the CI config. Don't assume
```
main
```
.

生成配置前，请确认：

Linear中已存在流水线——用户必须先在Linear中创建发布流水线（设置 → 发布）。每个流水线都有独立的访问密钥。
检测CI平台——查找
```
.github/workflows/*.yml
```
（GitHub Actions）、
```
.gitlab-ci.yml
```
（GitLab CI）、
```
.circleci/config.yml
```
（CircleCI）或其他CI配置文件。
检测默认分支——执行
```
git symbolic-ref refs/remotes/origin/HEAD
```
命令或查看CI配置文件。不要默认是
```
main
```
分支。

Step 2: Map pipelines, then ask

步骤2：映射流水线，然后提问

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
```
main
```
  , or
```
main
```
  + release branches (
```
release/*
```
  )?
- Version source — calendar (
```
2026.05
```
  ), semver (
```
1.2.0
```
  ), 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
```
workflow_dispatch
```
  , 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
```
--include-paths
```
.

首先列出用户独立发布的每个构建产物——每个产物对应一条独立的Linear流水线。流水线与阶段的混淆是配置过程中最常见的错误，因此当拆分不明确时，请应用下文“阶段 vs 流水线”中的测试方法。

按以下顺序提问：

CI平台——如果未自动检测到。
**您发布什么内容，面向谁？**明确提示常见的拆分场景：生产环境 vs 测试版/TestFlight、夜间构建或内部测试构建、预发布环境、跨平台构建（iOS、Android、Web）、单体仓库中的微服务。对于每个场景，应用测试：这些内容能否同时包含不同的提交？ 是 → 使用独立流水线。否（同一不可变构建产物依次通过多个环节）→ 单一流水线搭配多个阶段。
每条流水线：持续发布还是定时发布？
- 持续发布——每次部署完成一个发布。常见于夜间构建、内部测试构建，以及合并代码后立即发布的Web应用。
- 定时发布——发布内容会收集一段时间内的变更，经过多个阶段后再发布。常见于有版本号的移动应用和本地部署产品。
对于每条定时流水线，明确询问：
- 分支模型——仅使用
```
main
```
  分支，还是
```
main
```
  分支 + 发布分支（
```
release/*
```
  ）？
- 版本来源——日历版本（
```
2026.05
```
  ）、语义化版本（
```
1.2.0
```
  ），还是提交SHA？是从分支名称、CI变量、文件还是Git标签获取？
- 阶段——发布完成前需要经过哪些阶段（例如“代码冻结”、“测试中”）？阶段是单构建产物的流转环节，而非独立流水线。
- 自动化方式——完全通过
```
workflow_dispatch
```
  手动触发，还是自动触发（例如创建发布分支后自动推进阶段）？
单体仓库路径——如果多条流水线共享一个仓库，记录每条流水线对应的路径，并在Linear流水线设置中配置路径过滤，或通过
```
--include-paths
```
参数设置。

Step 3: Generate the CI configuration

步骤3：生成CI配置

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.

LINEAR_ACCESS_KEY_IOS

LINEAR_ACCESS_KEY_WEB

Platform	Pipeline Type	Example
GitHub Actions	Continuous	`github-actions-continuous/`
GitHub Actions	Scheduled	`github-actions-scheduled/`
GitLab CI	Continuous	`gitlab-ci-continuous/`
GitLab CI	Scheduled	`gitlab-ci-scheduled/`
CircleCI	Continuous	`circleci-continuous/`
CircleCI	Scheduled	`circleci-scheduled/`

Each scheduled example includes a monorepo note in the header explaining how to split workflows for path filtering per platform.

先查阅README获取最新的命令、参数、安装代码片段及命令目标规则。对于GitHub Actions，优先使用官方action（

linear/linear-release-action@v0

）；对于其他平台，按照README的安装部分使用CLI二进制文件。

选择匹配的示例模板，进行适配（分支模式、阶段名称、路径、版本格式），然后将其添加到现有工作流中或创建新工作流。多条流水线对应多个工作流或任务，每个任务使用独立的访问密钥调用CLI——每条流水线对应一个密钥（例如

LINEAR_ACCESS_KEY_IOS

、

LINEAR_ACCESS_KEY_WEB

）。

平台	流水线类型	示例链接
GitHub Actions	持续发布	`github-actions-continuous/`
GitHub Actions	定时发布	`github-actions-scheduled/`
GitLab CI	持续发布	`gitlab-ci-continuous/`
GitLab CI	定时发布	`gitlab-ci-scheduled/`
CircleCI	持续发布	`circleci-continuous/`
CircleCI	定时发布	`circleci-scheduled/`

每个定时发布示例的头部都包含单体仓库说明，解释如何拆分工作流以实现按平台进行路径过滤。

Step 4: Remind about secrets

步骤4：提醒配置密钥

Tell the user to add the

LINEAR_ACCESS_KEY

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.

告知用户将

LINEAR_ACCESS_KEY

密钥添加到CI环境中：

GitHub Actions：仓库设置 → 密钥和变量 → Actions → 新建仓库密钥
GitLab CI：设置 → CI/CD → 变量
CircleCI：项目设置 → 环境变量

访问密钥在Linear的流水线设置页面创建。每条流水线都有独立的访问密钥。

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.

Linear的发布流水线是一条独立的发布流，拥有自己的版本历史、当前发布版本和访问密钥。它不是CI流水线，而是Linear用于跟踪发布的单元，CI配置会调用CLI来更新它。独立发布的不同产品、环境或分发渠道对应不同的流水线。

流水线分为两种类型——持续发布和定时发布。每种类型的标准定义请查阅README的Pipeline Types章节。

Stages vs Pipelines

阶段 vs 流水线

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
```
HEAD
```
while production ships 1.2 from a release branch. Web staging auto-deploying from
```
main
```
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
```
main
```
(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

sync

(without

--release-version

) 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.

流水线是一条发布流。阶段是该流水线中某个发布的一个环节。混淆两者是配置过程中最常见的错误——编写任何配置前，请先通过以下测试判断。

测试方法： 两个内容能否同时处于流转状态，且包含不同的提交？

是 → 使用独立流水线。例如TestFlight基于
```
HEAD
```
构建，而生产环境从发布分支发布1.2版本；Web预发布环境自动从
```
main
```
分支部署，而生产环境滞后；热修复在一条流中发布，但未在另一条流中发布。
否，同一构建产物依次通过多个环节 → 单一流水线搭配多个阶段。例如发布版本1.2，经过代码冻结、测试、候选版本验证，然后发布。构建产物从未改变，仅阶段发生变化。

阶段是流程环节：“代码冻结”、“测试中”、“审核中”、“候选版本验证”。阶段仅存在于定时发布流水线中。

模糊场景——应用测试方法：

Beta / TestFlight：正式发布前基于同一构建产物的TestFlight验证 → 生产流水线的一个阶段。独立的夜间构建或内部测试渠道发布不同的构建产物 → 独立流水线。
预发布环境：自动从
```
main
```
分支部署（或包含生产环境没有的热修复）的预发布环境 → 独立流水线。与生产环境完全相同的构建产物，仅处于更早的推广环节 → 阶段。
单体仓库中的微服务：每个独立发布的微服务 → 独立流水线，通过路径过滤限定范围。这一点明确，微服务永远不会是阶段。

Linear中的阶段也可以被冻结。冻结阶段会让

sync

命令（不带

--release-version

参数）跳过当前发布，将提交合并到下一个发布中——这是代码冻结时的安全机制，而非将两条流水线合并为一条的方法。

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.

所有关于命令、参数、环境变量、命令目标、路径过滤、JSON输出及故障排查的内容都在linear-release README中。关于GitHub Action的输入参数及其与CLI参数的映射关系，请查阅action README。请始终查阅这些文档，而非依赖记忆——它们的更新会领先于本技能。

Checklist

检查清单

Full clone /
```
fetch-depth: 0
```
```
LINEAR_ACCESS_KEY
```
set as a secret (one per pipeline)
Correct binary platform (
```
linux-x64
```
,
```
darwin-arm64
```
, or
```
darwin-x64
```
)
Triggers on the correct branches (
```
main
```
for continuous;
```
main
```
+
```
release/*
```
for scheduled)
Monorepo: path filters set (in Linear config or via
```
--include-paths
```
), and separate workflows if using release branches

完整克隆 /
```
fetch-depth: 0
```
```
LINEAR_ACCESS_KEY
```
已设置为密钥（每条流水线一个）
正确的二进制平台（
```
linux-x64
```
、
```
darwin-arm64
```
或
```
darwin-x64
```
）
触发分支正确（持续发布用
```
main
```
；定时发布用
```
main
```
+
```
release/*
```
）
单体仓库：已设置路径过滤（在Linear配置中或通过
```
--include-paths
```
参数），如果使用发布分支则需拆分工作流