linear-release-setup

Name: linear-release-setup
Author: linear

Linear Release 設定

linear-release README 是指令、旗標、安裝、環境變數、路徑過濾與疑難排解的唯一權威來源。在產生任何設定前請先參考該文件——此技能專注於互動式設定流程以及 README 無法為使用者決定的管道模型選擇。

互動式流程

步驟 1：前置檢查

在產生設定前，請確認：

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。

步驟 2：對應管道，然後提問

首先列出使用者獨立發布的每個建置——每個建置都對應一個獨立的 Linear 管道。管道與階段的混淆是最常見的設定錯誤，因此每當拆分不明確時，請套用下方「階段 vs 管道」中的測試。

依序提問：

CI 平台——如果未自動偵測。
**你發布什麼，給誰？**明確提示常見的拆分候選項目：正式版 vs Beta 或 TestFlight、夜間版或內部測試版、暫存版、各平台版本（iOS、Android、Web）、單一儲存庫中各服務。針對每個候選項目，套用測試：這些項目能否同時包含不同的提交？ 是 → 分開的管道。否（同一個不可變的建置通過閘門）→ 一個管道搭配階段。
每個管道：持續型還是排程型？
- 持續型——每次部署完成一個發布。典型於夜間版、內部測試版以及合併即上線的網頁應用。
- 排程型——發布會隨時間收集變更，並在出貨前通過多個階段。典型於有版本號的行動應用與地端部署。
**測試：**團隊是否需要在發布出貨前追蹤它——為它命名、查看已排入哪些內容，或讓它通過不同階段（程式碼凍結、QA 等）？
- 是 → 排程型（發布在出貨前已作為進行中的事物存在）。
- 否 → 持續型（發布在出貨的當下才建立）。
針對每個排程管道，明確詢問：
- 分支模型——僅 main，還是 main + 發布分支（release/*）？
- 版本來源——日曆版本（2026.05）、語意化版本（1.2.0）或提交 SHA？從分支名稱、CI 變數、檔案或 Git 標籤衍生？
- 階段——發布在完成前會經過哪些階段（例如「程式碼凍結」、「QA 中」）？階段是同一個建置的閘門，而非獨立的管道。
- 自動化——全部手動透過 workflow_dispatch，還是自動化（例如建立發布分支時自動推進）？
單一儲存庫路徑——如果多個管道共用同一個儲存庫，請記錄每個管道所屬的路徑，並在 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。**精簡映像檔通常不包含 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：儲存庫設定 → 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 的管道類型章節以取得每種型態的標準說明。

階段 vs 管道

管道是一個發布串流。階段是該管道上一個發布內的一個環節。混淆這兩者是最常見的設定錯誤——在撰寫任何設定前，請先執行以下測試。

**測試：**兩個事物能否同時進行，且包含不同的提交？

是 → 分開的管道。TestFlight 執行在 HEAD 上，而正式版從發布分支出貨 1.2。Web 暫存版從 main 自動部署，而正式版落後。一個熱修復進入其中一個串流但未進入另一個。
否，這是同一個建置通過閘門 → 一個管道搭配階段。發布在 1.2 時被切出，經過程式碼凍結、QA 與 RC 驗證，然後出貨。建置從未改變；只有階段改變。

階段是流程閘門：「程式碼凍結」、「QA 中」、「審查中」、「RC 驗證」。它們只存在於排程型管道上。

模糊案例——套用測試：

**Beta / 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），如果使用發布分支則需分開的工作流程