agf-releasing-apple

name

agf-releasing-apple

description

Use when apple-release-engineer is about to build the signed distributable (TestFlight build / notarized DMG / internal package) from merged-to-main code (after apple code review + SIT Audit pass and merge, before apple-qa-engineer runs E2E/UAT). Provides the applicability gate, pre-flight checks, lane execution per channel, notarization, real-output smoke test, hand-off, and the release-report skeleton. Pairs with deployment.md §7 "Apple 发布" contract and slash /agf-apple-release.

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

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

适用门

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

• 角色 = 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>

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）：

  spctl -a -vv /path/to/App.app          # 期望 "accepted ... Notarized Developer ID"
  hdiutil attach <dmg> && 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/<feature>-apple-<YYYY-MM-DD>.md（pool=1，无 agf-matrix frontmatter）：

# Apple 发布报告 — [Feature]

- **Date**: YYYY-MM-DD
- **Releaser**: apple-release-engineer ([model name])
- **构建 commit (merged main)**: [short SHA]
- **渠道 / lane**: [beta | release_appstore | release_dmg | 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 <lane>
（贴关键输出：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（✅/❌）即可。