解析 Mantle 的 GitHub Actions 自动化体系:CI 构建、CocoaPods 发布与 Token 管理

原创2026-10-13 16:57:291,902 阅读
文章标签:移动开发

解析 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 环境),执行链路为:

  1. 检出代码,并执行 git submodule update --init --recursive 更新子模块。仓库的 .gitmodules 中登记了 Carthage/Checkouts 下的 Nimble、Quick、xcconfigs 等测试相关子模块,发布前同步它们是保证可构建性的前提;
  2. 从当前 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;

  1. 使用 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_TOKEN Secret,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。

登录后查看全文
Mantle