解析 Mantle 的 GitHub Actions 自动化体系:CI 构建、CocoaPods 发布与 Token 管理
解析 Mantle 的 GitHub Actions 自动化体系:CI 构建、CocoaPods 发布与 Token 管理
Mantle 仓库使用 GitHub Actions 来自动化版本发布、检查构建质量以及处理 Issue 维护等任务,其完整说明见 ACTIONS.md。本篇基于该文档并结合仓库内实际的 workflow 配置文件,逐一拆解 Mantle 的三条核心自动化流水线(cocoapods-publish、stale、CI/xcodebuild),并完整给出 CocoaPods Trunk Token 的申请与更新流程。读完本文,你不仅能在自己的 Cocoa 项目中复刻“tag 推送到 CocoaPods 自动发布”的完整链路,还能掌握 Token 轮换的每一步操作细节。
总览:如何查看 Mantle 的 GitHub Actions
ACTIONS.md 开篇说明:Mantle 借助 GitHub Actions 来"automate deployment, check build quality, & other tasks"(自动化部署、检查构建质量及其他任务)。在仓库根目录下执行以下命令即可打开 workflows 目录浏览所有工作流定义:
open .github/workflows
当前仓库中实际存在四个 workflow 文件,分别对应文档中描述的三类职责:
| Workflow 文件 | 对应 ACTIONS.md 章节 | 触发方式 |
|---|---|---|
| .github/workflows/cocoapods-publish.yml | cocoapods-publish | 推送新 tag / 手动触发 |
| .github/workflows/stale.yml | stale | 每小时定时(cron) |
| .github/workflows/ci-pull-requests-only.yml | xcodebuild(CI) | 针对 master 分支的 pull request |
| .github/workflows/carthage-artifact-release-upload.yml | 文档未单独成节(补充) | 推送新 tag |
CONTRIBUTING.md 中也有一个 "GitHub Actions" 小节,明确指向本文所依据的 ACTIONS.md 文档,说明这套自动化是项目贡献流程的一部分。
cocoapods-publish:从 git tag 自动发布新版 podspec
触发条件与整体流程
ACTIONS.md 中对该工作流的描述是:
向 CocoaPods 发布新版本,需要由受信任的 owner 账户提交一份携带正确 tag 与 version 的 podspec。每当有新 tag 被推送,工作流会自动以 tag 中提取的版本号提交 podspec。
对照实际配置 cocoapods-publish.yml,触发条件为:
on:
push:
tags:
- '*'
workflow_dispatch:
即推送任意 tag 时自动执行,同时也支持通过 workflow_dispatch 手动触发。整个 job 运行在 macos-latest 上(发布 Cocoa 依赖必须使用 macOS 环境),执行链路为:
- 检出代码,并执行
git submodule update --init --recursive更新子模块。仓库的 .gitmodules 中登记了Carthage/Checkouts下的 Nimble、Quick、xcconfigs 等测试相关子模块,发布前同步它们是保证可构建性的前提; - 从当前 tag 提取版本号并写入 step output:
echo ::set-output name=VERSION::${GITHUB_REF/refs\/tags\//}
这一行(cocoapods-publish.yml 第 19 行)利用 Bash 字符串替换,把 GITHUB_REF 中 refs/tags/ 前缀剥掉,例如推送 1.0.61 时得到 VERSION=1.0.61;
- 使用
jq将版本号同时写入 podspec 的version与source.tag两个字段,然后先 lint 再 push:
# Modify the podspec with the version & tag and run lint on it
jq --arg VERSION "$MANTLE_VERSION" '. | .version |= $VERSION | .source.tag |= $VERSION' Mantle.podspec.json > tmp/Mantle.podspec.json
pod spec lint tmp/Mantle.podspec.json --skip-import-validation --allow-warnings
# Print out the podspec we'll submit
cat tmp/Mantle.podspec.json
# Time to ship!
pod trunk push tmp/Mantle.podspec.json --skip-import-validation --allow-warnings
这里体现了文档所说的"version 从 tag 中自动获取":仓库内维护的 Mantle.podspec.json 并不硬编码具体版本号,而是发布时由 workflow 动态注入 version 和 source.tag,保证 podspec 与 git tag 严格一致。注意 lint 与 push 都带了 --skip-import-validation --allow-warnings 参数——跳过 import 校验可避免 macOS 环境下的签名/沙箱问题,--allow-warnings 则允许在存在告警时通过校验,这是 Cocoa 项目 CI 发布的常见组合。
推送 podspec 需要身份凭证,工作流通过环境变量注入仓库 Secret:
env:
COCOAPODS_TRUNK_TOKEN: ${{ secrets.COCOAPODS_TRUNK_TOKEN }}
谁有权发布:podspec 中的 owners
ACTIONS.md 指出:podspec 中列出的 owners 都可以生成新的 Trunk token,并将其添加到本仓库 Settings 页面的 Secrets 标签页中。查看 Mantle.podspec.json,authors 字段列出了三位 owner:
"authors": {
"Robert Böhnke": "robb@robb.is",
"David Caunt": "dcaunt@gmail.com",
"Jan Gorman": "gorman.jan@gmail.com"
}
因此 CocoaPods 侧的权限边界与 podspec 中的 authors 名单保持一致——这也是为什么文档强调"由受信任的 owner 账户提交 podspec"。
更新 CocoaPods Trunk Token(完整操作手册)
这是 ACTIONS.md 中最具实操价值的部分,值得原样继承并逐条说明。文档指出:CocoaPods Trunk token 会随时间过期,大约每 5 个月需要更新一次。
有资格更新 token 的人需同时满足:
- 是 podspec 中列出的 owner,拥有仓库权限与 CocoaPods 所有权声明(ownership claims);
- 能够接收
mantle-cocoapods@robb.is邮箱的来信(该邮箱由 robb 设立)。
满足条件后,按以下 4 步操作:
第 1 步:注册 CocoaPods Trunk 会话
pod trunk register mantle-cocoapods@robb.is 'Mantle GitHub Actions' --description='Mantle GitHub Actions'
第 2 步:激活会话
一封邮件会发送到 mantle-cocoapods@robb.is,点击邮件中的链接完成会话激活。
第 3 步:获取 token
pod trunk me --verbose
会看到类似如下的输出:
opening connection to trunk.cocoapods.org:443...
opened
starting SSL for trunk.cocoapods.org:443...
SSL established, protocol: TLSv1.2, cipher: ECDHE-RSA-AES128-GCM-SHA256
<- "GET /api/v1/sessions HTTP/1.1\r\nContent-Type: application/json; charset=utf-8\r\nAccept: application/json; charset=utf-8\r\nUser-Agent: CocoaPods/1.7.4\r\nAuthorization: Token XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\r\nAccept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3\r\nHost: trunk.cocoapods.org\r\n\r\n"
-> "HTTP/1.1 200 OK\r\n"
-> "Date: Sun, 22 Sep 2019 05:11:46 GMT\r\n"
-> "Connection: keep-alive\r\n"
-> "Strict-Transport-Security: max-age=31536000\r\n"
-> "Content-Type: application/json\r\n"
-> "Content-Length: 1491\r\n"
-> "X-Content-Type-Options: nosniff\r\n"
-> "Server: thin 1.6.2 codename Doc Brown\r\n"
-> "Via: 1.1 vegur\r\n"
-> "\r\n"
其中 Authorization: Token 后面的 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 就是 CocoaPods Trunk Token。文档特别强调:该 token 永远不应被公开发布。
第 4 步:写入仓库 Secret
进入 Mantle 的 GitHub 页面 Settings -> Secrets,将该 token 添加为名为 COCOAPODS_TRUNK_TOKEN 的 secret——正是 cocoapods-publish.yml 第 22 行 通过 ${{ secrets.COCOAPODS_TRUNK_TOKEN }} 读取的那个名字。至此,下一次 tag 推送即可完成自动发布。
stale:自动标记并关闭长期无响应的 Issue 与 PR
ACTIONS.md 对 stale 的描述是:Mark stale issues and pull requests 工作流是项目的 GitHub bot 行为——将 30 天无任何活动的 Issue 与 PR 标记为 stale,若 5 天内仍无响应,则自动关闭。
实际配置 stale.yml 与文档描述一一对应:
on:
schedule:
- cron: "0 * * * *"
jobs:
stale:
runs-on: ubuntu-latest
steps:
- uses: actions/stale@v1
with:
repo-token: ${{ secrets.GITHUB_TOKEN }}
days-before-close: 5
days-before-stale: 30
stale-issue-label: 'stale'
stale-issue-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.'
stale-pr-label: 'stale'
stale-pr-message: 'This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.'
几个值得注意的实现细节:
- 该 job 运行在
ubuntu-latest上,因为actions/stale只调用 GitHub API 操作标签,无需 macOS 或 Xcode 环境; cron: "0 * * * *"表示每小时执行一次,保证"30 天 / 5 天"的判定及时生效;- 使用 GitHub 自动注入的
${{ secrets.GITHUB_TOKEN }}而非任何长期凭证,权限最小化; - Issue 与 PR 使用同一个
stale标签,但消息文案在 workflow 中是分别配置的两项(stale-issue-message/stale-pr-message)。
xcodebuild:保障构建质量的 CI 流水线
ACTIONS.md 中的 xcodebuild 小节描述较简:
该工作流在 commit 推送时执行构建,确保不会破坏构建。
而当前仓库中实际承载这一职责的文件是 ci-pull-requests-only.yml。从源码结构看,该 workflow 现由针对 master 分支的 pull_request 事件触发,包含两个 job:
Job 1:Carthage Build
jobs:
Carthage-Build:
env:
DEVELOPER_DIR: /Applications/Xcode_11.7.app/Contents/Developer
name: Carthage Build
runs-on: macOS-latest
steps:
- name: Checkout the Git repository
uses: actions/checkout@v2
- name: Update submodules
run: git submodule update --init --recursive
- name: Verify Carthage build
run: carthage build --no-skip-current
这一步验证 Mantle 以 Carthage 依赖方式被消费时能够完整构建。--no-skip-current 确保当前项目本身也被纳入 Carthage 的构建图,而不是仅构建其依赖。Mantle 的 README 将 Carthage 列为官方支持的集成方式之一,因此这条校验对应的是真实用户场景。
Job 2:Tests —— 四平台矩阵构建与测试
Tests:
runs-on: macos-latest
env:
DEVELOPER_DIR: /Applications/Xcode_11.7.app/Contents/Developer
strategy:
matrix:
config:
- scheme: "Mantle Mac"
action: test
sdk: macosx
destination: "arch=x86_64"
- scheme: "Mantle iOS"
action: test
sdk: iphonesimulator
destination: "name=iPhone 11"
- scheme: "Mantle-tvOS"
action: test
sdk: appletvsimulator
destination: "name=Apple TV"
- scheme: "Mantle-watchOS"
action: build
sdk: watchsimulator
destination: "name=Apple Watch Series 4 - 40mm"
矩阵覆盖了四个平台,与仓库中 Mantle.xcodeproj/xcshareddata/xcschemes 下的四个共享 scheme 文件(Mantle Mac.xcscheme、Mantle iOS.xcscheme、Mantle-tvOS.xcscheme、Mantle-watchOS.xcscheme)完全对应。每个配置项的含义如下:
| 平台 | scheme | 动作 | SDK | destination |
|---|---|---|---|---|
| macOS | Mantle Mac | test | macosx | arch=x86_64 |
| iOS | Mantle iOS | test | iphonesimulator | iPhone 11 |
| tvOS | Mantle-tvOS | test | appletvsimulator | Apple TV |
| watchOS | Mantle-watchOS | build | watchsimulator | Apple Watch Series 4 - 40mm |
值得注意的是 watchOS 一项只执行 build 而不跑 test,其余三项均为 test;最终统一通过以下命令执行:
xcodebuild ${{ matrix.config.action }} -workspace Mantle.xcworkspace -scheme "${{ matrix.config.scheme }}" -sdk "${{ matrix.config.sdk }}" -destination "${{ matrix.config.destination }}" RUN_CLANG_STATIC_ANALYZER=NO
几个可复用的工程化细节:
- 用
DEVELOPER_DIR锁定 Xcode 11.7:通过环境变量把 CI 的开发者目录固定到/Applications/Xcode_11.7.app/Contents/Developer,避免 macOS runner 预装 Xcode 版本漂移导致的不可复现构建; - 使用 workspace 而非 project:
-workspace Mantle.xcworkspace是因为 Mantle 通过 Carthage 集成 Quick/Nimble 等测试依赖(见 .gitmodules),workspace 同时编排了工程与外部框架 target; RUN_CLANG_STATIC_ANALYZER=NO:在 CI 测试中显式关闭静态分析,以稳定耗时与结果;- 所有 job 前都先执行
git submodule update --init --recursive,与发布工作流保持一致的子模块同步习惯。
补充:tag 推送时的 Carthage 制品上传
ACTIONS.md 未单独成节,但仓库中还存在 carthage-artifact-release-upload.yml,与 cocoapods-publish 共享"推送 tag 触发"的语义,负责 Carthage 渠道的发布:
carthage build --no-skip-current && carthage archive
随后通过 actions/create-release@v1 以 tag 创建 Release,并用 actions/upload-release-asset@v1 将 ./$FRAMEWORK_NAME.framework.zip(FRAMEWORK_NAME=Mantle)作为 release 资产上传,内容类型为 application/zip。它与 cocoapods-publish 共同构成 Mantle 面向两个主要分发渠道(CocoaPods 与 Carthage)的自动发布闭环,另外的 Swift Package Manager 渠道则由仓库根目录的 Package.swift 直接随源码分发,无需额外的 workflow 步骤。
小结:可复用的 CI/CD 实践清单
从 Mantle 的 GitHub Actions 体系(ACTIONS.md 与 .github/workflows 目录)中,可以提炼出对 Cocoa/Cocoa Touch 开源库颇具参考价值的一组实践:
- tag 即版本号:podspec 不硬编码版本,由 workflow 用
jq在发布时注入version与source.tag,先pod spec lint再pod trunk push; - 凭证最小化与轮换:发布只依赖一个
COCOAPODS_TRUNK_TOKENSecret,stale bot 用自动注入的GITHUB_TOKEN;文档为约 5 个月一次的 token 轮换提供了可复制的完整操作手册; - 构建质量门禁:Carthage 构建校验 + 四平台 xcodebuild 矩阵(test/build 区分),并用
DEVELOPER_DIR锁定工具链版本; - Issue 维护自动化:
actions/stale@v1按 30/5 天阈值自动标记与关闭,配合每小时 cron 及时生效。
相关入口文件索引:ACTIONS.md、.github/workflows/cocoapods-publish.yml、.github/workflows/stale.yml、.github/workflows/ci-pull-requests-only.yml、.github/workflows/carthage-artifact-release-upload.yml、Mantle.podspec.json、.gitmodules、CONTRIBUTING.md。