linear-release-setup

Linear Release 设置

linear-release README 是命令、标志、安装、环境变量、路径过滤和故障排除的权威来源。在生成任何配置之前请先获取它——本技能专注于交互式设置工作流以及 README 无法为用户做出的管道建模决策。

交互式工作流

步骤 1：预检

在生成配置之前，确认：

1. Linear 中存在管道——用户必须先在 Linear 中创建发布管道（设置 → 发布）。每个管道都有自己的访问密钥。
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 管道。管道与阶段的混淆是最常见的设置错误，因此当拆分不明显时，应用下面的“阶段 vs 管道”测试。

按顺序询问：

1. CI 平台——如果未自动检测到。

2. **你发布什么，给谁？**明确提示常见的拆分候选：生产版 vs 测试版或 TestFlight、夜间版或内部版、预发布版、按平台构建（iOS、Android、Web）、单体仓库中的按服务构建。对于每个候选，应用测试：这些能否同时持有不同的提交？ 是 → 单独的管道。否（相同的不可变构建通过门控移动）→ 一个管道包含阶段。

3. 对于每个管道：持续还是定时？

   • 持续——每次部署完成一个发布。典型用于夜间版、内部版以及在合并时发布的 Web 应用。
   • 定时——发布随时间收集更改，并在发布前通过阶段移动。典型用于版本化的移动端和本地部署。

   **测试：**团队是否需要在发布之前跟踪它——命名它、查看其中排队的内容，或将其移过阶段（代码冻结、QA 等）？

   • 是 → 定时（发布在发布之前作为一个进行中的事物存在）。
   • 否 → 持续（发布在发布时刻创建）。

4. 对于每个定时管道，明确询问：

   • 分支模型——仅 main，还是 main + 发布分支（release/*）？
   • 版本来源——日历版本（2026.05）、语义版本（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 的安装部分使用 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 动态加载器而失败，并显示不明确的“未找到”错误。
• **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/

每个定时示例在头部包含一个单体仓库注释，解释如何按平台拆分工作流以进行路径过滤。

步骤 4：提醒密钥

告诉用户将 LINEAR_ACCESS_KEY 密钥添加到他们的 CI 环境中：

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

访问密钥在 Linear 中从管道的设置页面创建。每个管道有自己的访问密钥。

关键概念

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

管道有两种类型——持续和定时。请参阅 README 的管道类型部分以获取每种类型的规范描述。

阶段 vs 管道

一个管道是一个发布流。一个阶段是该管道上一个发布内的一个阶段。混淆两者是最常见的设置错误——在编写任何配置之前，先进行下面的测试。

**测试：**两个事物能否同时进行，持有不同的提交？

• 是 → 单独的管道。TestFlight 在 HEAD 上运行，而生产版从发布分支发布 1.2。Web 预发布从 main 自动部署，而生产版滞后。一个热修复进入一个流但不进入另一个。
• 否，它是同一个构建通过门控移动 → 一个管道包含阶段。发布在 1.2 处切割，经过代码冻结、QA 和 RC 浸泡，然后发布。构建从未改变；只有阶段改变。

阶段是流程门控：“代码冻结”、“QA 中”、“审核中”、“RC 浸泡”。它们只存在于定时管道上。

模糊情况——应用测试：

• **测试版 / TestFlight。**在 GA 之前对_相同构建_进行 TestFlight 浸泡 → 生产管道上的阶段。一个单独的夜间版或内部版渠道发布_不同构建_ → 自己的管道。
• **预发布。**从 main 自动部署（或运行生产版没有的热修复）的预发布 → 单独的管道。持有与生产版完全相同构建的预发布，只是处于推广路径的早期 → 阶段。
• **按服务单体仓库。**每个独立发布的服务 → 自己的管道，通过路径过滤器限定范围。明确；服务从来不是阶段。

阶段也可以在 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/*）
• [ ] 单体仓库：设置路径过滤器（在 Linear 配置中或通过 --include-paths），如果使用发布分支，则使用单独的工作流