linear-release-setup

Linear 发布设置

linear-release README 是命令、标志、安装、环境变量、路径筛选和故障排除的权威来源。生成任何配置前，请先获取该 README——本技能侧重于交互式设置工作流，以及 README 无法替用户做出的流水线建模决策。

交互式工作流

第 1 步：预检

生成配置前，请确认：

1. Linear 中已存在流水线 — 用户必须先在 Linear 中创建发布流水线（Settings → Releases）。每条流水线都有自己的访问密钥。
2. 检测 CI 平台 — 查找 .github/workflows/*.yml（GitHub Actions）、.gitlab-ci.yml（GitLab CI）、.circleci/config.yml（CircleCI）或其他 CI 配置。
3. 检测默认分支 — 检查 git symbolic-ref refs/remotes/origin/HEAD 或 CI 配置。不要假定是 main。

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

先列出用户独立发布的所有构建——每个构建对应一条独立的 Linear 流水线。流水线与阶段混淆是最常见的设置错误，因此只要拆分方式不明确，就使用下方“阶段与流水线”中的判断方法。

按顺序提问：

1. CI 平台 — 如果无法自动检测。

2. 你们发布什么，面向哪些对象？ 明确询问常见的拆分候选项：生产版与 beta 版或 TestFlight、夜间构建或内部试用构建、预发布环境、按平台拆分的构建（iOS、Android、web）、单体仓库中的各项服务。对每个候选项应用以下判断：它们能否同时包含不同的提交？ 能 → 分成独立流水线。不能（同一个不可变构建在不同关卡间流转）→ 使用一条包含多个阶段的流水线。

3. 每条流水线：持续发布还是定期发布？

   • 持续发布 — 每次部署都会完成一次发布。常见于夜间构建、内部试用构建，以及合并后即发布的 web 应用。
   • 定期发布 — 发布会在一段时间内收集变更，并在发布前经过多个阶段。常见于有版本号的移动应用和本地部署软件。

   **判断方法：**团队是否需要在发布之前跟踪某次发布——为其命名、查看其中排队的内容，或推动其经过不同阶段（代码冻结、QA 等）？

   • 是 → 定期发布（发布在正式发布前就以进行中事项的形式存在）。
   • 否 → 持续发布（发布在正式发布时创建）。

4. 对于每条定期发布的流水线，请明确询问：

   • 分支模型 — 仅使用 main，还是使用 main + 发布分支（release/*）？
   • 版本来源 — 日历版本（2026.05）、semver（1.2.0）还是提交 SHA？版本号根据分支名称、CI 变量、文件还是 git 标签生成？
   • 阶段 — 发布在完成前要经过哪些阶段（例如“代码冻结”“QA 中”）？阶段是针对同一个构建的关卡，不是独立流水线。
   • 自动化 — 全部通过 workflow_dispatch 手动触发，还是自动化执行（例如创建发布分支后自动推进）？

5. 单体仓库路径 — 如果多条流水线共用一个仓库，请记录每条流水线对应的路径，并在 Linear 流水线设置中配置路径筛选，或使用 --include-paths。

第 3 步：生成 CI 配置

请先获取 README，确认当前的命令、标志、安装代码片段和命令目标规则。对于 GitHub Actions，优先使用官方 action（linear/linear-release-action@v0）；对于其他平台，根据 README 的 Installation 部分使用 CLI 二进制文件。

运行时要求（基于 Docker 的 CI）

运行 linear-release 作业的镜像必须提供：

• glibc。 预构建的二进制文件动态链接到 glibc，无法在 Alpine/musl 镜像上运行。请选择 Debian/Ubuntu 基础镜像（debian:bookworm-slim、ubuntu:24.04、buildpack-deps:bookworm）。避免使用 alpine、任何 *-alpine 标签以及 curlimages/curl——在 musl 上，由于缺少 glibc 动态加载器，二进制文件会报出含义不明的 “not found” 错误。
• git。 精简镜像不包含它。请显式安装：apt-get update && apt-get install -y git。
• curl（或 wget）。用于下载 CLI 二进制文件。

GitLab CI：检查现有变量

如果已存在 .gitlab-ci.yml，请检查其中的默认 variables: 块。linear-release 作业需要完整克隆，因此如果项目默认设置会阻止完整克隆，请在作业级别覆盖：

• GIT_STRATEGY: clone——如果项目默认值为 none 或 empty（两者都会完全跳过克隆），则为必需设置。
• GIT_DEPTH: 0——无论如何都要在 linear-release 作业中设置此项。新的 GitLab 项目默认进行深度为 20 的浅克隆，项目也常会将深度设得更小。

选择匹配的示例模板，对其进行调整（分支模式、阶段名称、路径、版本格式），然后将其添加到现有工作流，或创建新的工作流。多个流水线意味着需要多个工作流或作业，并且每个都使用自己的访问密钥调用 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/

每个定时示例的标题中都包含一条 monorepo 说明，解释如何按平台拆分工作流以进行路径筛选。

第 4 步：提醒用户添加密钥

告知用户将 LINEAR_ACCESS_KEY 密钥添加到 CI 环境：

• GitHub Actions：Repository Settings → Secrets and variables → Actions → New repository secret
• GitLab CI：Settings → CI/CD → Variables
• CircleCI：Project Settings → Environment Variables

访问密钥在 Linear 的流水线设置页面中创建。每个流水线都有自己的访问密钥。

关键概念

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

流水线分为两种类型——持续式和定时式。每种类型的权威说明请参阅 README 的流水线类型部分。

阶段与流水线

流水线是一条发布流。阶段是该流水线中一次发布所经历的一个环节。混淆两者是最常见的配置错误；编写任何配置前，请先完成下面的测试。

**测试：**是否可能有两项任务同时进行，且各自持有不同的提交？

• 是 → 使用单独的流水线。例如，TestFlight 正在运行 HEAD，同时生产环境从发布分支发布 1.2 版；Web 预发布环境从 main 自动部署，而生产环境进度较慢；或者一个流中合入了热修复，另一个流中却没有。
• 否，同一个构建只是在各道关卡之间流转 → 使用一个带阶段的流水线。一次发布定在 1.2 版，然后经历代码冻结、QA 和 RC 浸泡测试，最后发布。构建始终不变，变化的只有所处阶段。

阶段是流程关卡，例如“代码冻结”“QA 中”“审核中”“RC 浸泡测试”。它们只存在于按计划发布的流水线中。

容易混淆的情况——请运用测试判断：

• Beta / TestFlight。 GA 前在 TestFlight 上对_同一构建_进行浸泡测试 → 作为生产流水线中的一个阶段。单独的夜间版或内部试用渠道发布_不同构建_ → 使用独立的流水线。
• 预发布环境。 从 main 自动部署（或运行着生产环境没有的热修复）的预发布环境 → 使用单独的流水线。与生产环境持有完全相同的构建，只是在晋级流程中更早一步 → 作为一个阶段。
• 按服务划分的 monorepo。 每个独立发布的服务 → 使用各自的流水线，并通过路径过滤器限定范围。此情况没有歧义；服务绝不会是阶段。

也可以在 Linear 中将阶段冻结。冻结阶段后，sync（不带 --release-version）会跳过该发布，并将提交归入下一个发布——这是代码冻结期间的安全保障。这是流程工具，而不是把两条流水线硬塞进一条的方法。

参考

有关命令、标志、环境变量、命令目标、路径过滤、JSON 输出和故障排除的所有信息，都在 linear-release README 中。有关 GitHub Action 输入及其与 CLI 标志的对应关系，请参阅 action README。请务必获取这些文档，不要依赖记忆——它们的更新速度比此技能更快。

检查清单

• 完整克隆 / fetch-depth: 0（GitLab：GIT_DEPTH: 0，且 GIT_STRATEGY 不能为 none）
• 将 LINEAR_ACCESS_KEY 设置为机密（每条流水线一个）
• 使用正确的二进制平台（linux-x64、darwin-arm64 或 darwin-x64）
• 基于 Docker 的 CI：使用 glibc 基础映像（不能使用 Alpine/musl），并确保 git 和 curl 可用
• 在正确的分支上触发（持续发布使用 main；按计划发布使用 main + release/*）
• Monorepo：设置路径过滤器（在 Linear 配置中或通过 --include-paths），如果使用发布分支，还要配置单独的工作流