Agf Releasing Apple

Releasing the Apple distributable (sign → notarize → package → smoke)

把合并到 main 后的干净代码构建成签名分发包，冒烟自检通过后交接 apple-qa-engineer。本 skill 是 apple-release-engineer 的分步 runbook；契约 SSOT 是 [deployment.md §7](../../standards/deployment.md)，流水线决策是 [ADR-009](../../../docs/adr/009-apple-release-pipeline.md)。

适用门

满足以下全部才进入构建：

• 角色 = apple-release-engineer（deploy-only，不修业务源码；apple/fastlane/ 配置是可写域）。
• 目标是 Apple 原生链路（apple/ 工程）。Web docker UAT → 归 deploy-engineer；小程序体验版 → 归 miniapp 轨。均不适用。
• apple code review（含 SIT Audit）已通过且已合并到 main，product-lead 已确认"构建分发包"（对话内确认或 /agf-apple-release 手动触发），且 PRD 已声明渠道。

任一不满足 → 不构建，SendMessage product-lead 说明缺什么。

前置检查（构建前必须逐项确认）

• [ ] main 干净且最新：git status 无未提交改动，记录构建 commit SHA（git rev-parse --short HEAD）。
• [ ] 工具链可用：xcodebuild -version / bundle exec fastlane --version 正常返回。
• [ ] 签名材料就位且不入库：App Store Connect API key（.p8）路径 / key id / issuer id 经环境变量可达；match 仓可访问（fastlane match 能同步证书 + profile）。任何 .p8 / .p12 / .mobileprovision 都不得出现在 git 工作区（scan-secrets / pre-commit 兜底）。
• [ ] 渠道已声明：PRD / task 写明渠道，映射到 lane（见下表）。
• [ ] 版本号就绪：marketing version 符合 versioning.md；build number 在该渠道单调递增。

任一不勾 → 不构建，先 SendMessage product-lead 解决先决条件。

渠道 → lane 执行（映射 SSOT 见 deployment.md §7.2）

cd apple && bundle exec fastlane 

| lane | 渠道 | 关键动作 | |---|---|---| | beta | TestFlight 内测 | match(type: appstore) → build_app → pilot（上传 + 等待处理完成） | | release_appstore | App Store 上架 | match → build_app → deliver（含元数据 / 截图 / 提审包） | | release_dmg | macOS 直发 | match(type: developer_id) → build_app → notarize（notarytool + API key）→ DMG 打包（hdiutil / create-dmg） | | release_internal | 企业 / 内部 | macOS：Developer ID 包内部散发；iOS in-house lane 仅在 Enterprise 会籍就位后启用（ADR-009） |

• 公证有 Apple 侧分钟级排队——notarize 等待完成后才继续，禁止跳过等待声明成功。
• 构建产物路径 / build 号记录进报告。

冒烟（真实输出，非 dry-run）

只接受真实证据，拒绝 "构建 exit 0 就算" / "应该能装"：

• macOS 直发（DMG）：

``bash spctl -a -vv /path/to/App.app # 期望 "accepted ... Notarized Developer ID" hdiutil attach && open App.app # 干净用户目录实际启动 ` 贴 spctl` 真实输出 + app 启动后关键路径点查（主窗口出现 / 核心视图可达）。

• TestFlight（iOS / macOS App Store 系）：
• pilot 上传完成 + App Store Connect 处理状态到 "Ready to Test"（贴 fastlane 输出的 build 号 + 状态行）
• 至少一台设备 / 模拟器装 TestFlight build 实际启动点查
• App Store 提审包：deliver 校验通过输出（元数据 / 截图齐全），不实际点提交（提审动作由 product-lead 确认后执行）。

任一非预期 → gate = ❌ 构建失败。

冒烟范围说明：冒烟只证明"包出得来、装得上、跑得起"，不是 E2E——AC 验收归 apple-qa-engineer。冒烟暴露代码层缺陷（启动即崩 / 核心视图白屏），采集证据退回 product-lead，不自己改 apple/App*。

二元 gate

• ✅ 构建成功（冒烟通过） —— 前置全过 + lane 完成 + 公证/处理完成 + 冒烟真实证据。
• ❌ 构建失败 —— 任一环节失败；报告标明签名/公证/打包配置问题（自己重跑）还是代码问题（退回 PL → apple-dev）。

不发明新 verdict 词表（保 CLAUDE.md「Verdict 词表 4 套」硬事实）。

交接

报告落盘后立即（不等用户问）SendMessage product-lead：

SendMessage({to: "product-lead", message: "发布构建完成: [功能名]\n报告: docs/deploy/[feature]-apple-[YYYY-MM-DD].md\n渠道/lane: [lane]\n分发包: [TestFlight build 号 / DMG 路径]\n构建 commit: [SHA]\n结果: ✅ 构建成功（冒烟通过） / ❌ 构建失败", summary: "Apple 发布构建: [功能名]"})

✅ → PL 触发 apple-qa-engineer 对该分发包跑 E2E；❌ → PL 决策重跑（配置）/ 退回 apple-dev（代码）。

发布报告骨架

落到 docs/deploy/-apple-.md（pool=1，无 agf-matrix frontmatter）：

````markdown

Apple 发布报告 — [Feature]

• Date: YYYY-MM-DD
• Releaser: apple-release-engineer ([model name])
• 构建 commit (merged main): [short SHA]
• 渠道 / lane: [beta | releaseappstore | releasedmg | release_internal]
• Target: [macos | ios | universal]
• 版本: [marketing version] ([build number])

分发包定位（交给 apple-qa-engineer 作测试目标）

| 项 | 值 | |---|---| | TestFlight build 号 / DMG 路径 | ... | | 安装方式 | TestFlight 邀请 / DMG 挂载 |

前置检查

• [x] main 干净（commit [SHA]）
• [x] 工具链可用（xcodebuild / fastlane 版本）
• [x] 签名材料就位（match 同步成功；无 .p8/.p12 入库）
• [x] 渠道已声明 + 版本号就绪

Lane 执行

bundle exec fastlane 
（贴关键输出：match 同步 / build_app 产物 / pilot 或 notarize 完成行）

冒烟证据（真实输出，非 dry-run）

• 公证/处理状态：（贴 spctl -a -vv 输出 / TestFlight "Ready to Test" 状态行）
• 实际启动点查：（装包启动 + 关键路径可达的证据）

Release Gate

Verdict: ✅ 构建成功（冒烟通过） / ❌ 构建失败 （失败时：问题归类 = 签名/公证/打包配置（自己重跑） / 代码（退回 product-lead → apple-dev）+ 证据）

Hand-off

✅ → SendMessage product-lead（附分发包定位）→ PL 触发 apple-qa-engineer E2E ❌ → SendMessage product-lead（附失败定位）→ PL 决策重跑 / 退回 apple-dev

````

完成前的验证

• [ ] 构建源确为合并后的 main（记了 commit SHA）？
• [ ] 签名走 match 正规链路（无 ad-hoc 绕过 / 无关公证）？
• [ ] 公证 / TestFlight 处理等到完成状态才声明（非 exit 0 即成功）？
• [ ] 冒烟每条都有真实输出（spctl / 状态行 / 启动证据）？
• [ ] gate 是二元（✅/❌），失败时标了配置 vs 代码归类？
• [ ] 报告落盘 + SendMessage product-lead 已发（附分发包定位）？

任一不行 → 不要声明构建成功，回去补。

反模式

• ❌ 构建未合并分支 —— 必须从合并后的 main 拉。
• ❌ ad-hoc 签名 / 关沙盒 / 跳公证"先测了再说" —— QA 测的必须是真实分发形态。
• ❌ .p8 / .p12 / match 密码写进任何入库文件 —— 环境变量 / Keychain only。
• ❌ 公证还在排队就声明成功 —— 等 "Accepted" / "Ready to Test"。
• ❌ 冒烟暴露代码 bug 时自己改 apple/App* —— 越界；采证退回 PL → apple-dev。
• ❌ 给发布门发明多档 verdict —— 二元 gate（✅/❌）即可。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pcliangx
• Source: pcliangx/AppGenesisForge
• License: MIT

Install and usage instructions live in the source repository linked above.