iOS构建Fastlane与GitHub Actions配置：签名失败排查与解决

我正在使用Fastlane和GitHub Actions自动化iOS应用的构建与部署流程，目标是通过CI/CD流水线将应用构建并分发至TestFlight。已配置GitHub Action工作流，但在Fastlane iOS设置阶段遇到代码签名问题。

已完成的操作 #

• 创建Fastfile，用于处理构建及上传至TestFlight的lane；
• 在GitHub中配置所需密钥（如APP_STORE_CONNECT_API_KEY、MATCH_PASSWORD等）；
• 配置Match以管理签名证书。

GitHub Actions工作流配置 #

name: iOS CI/CD

on:
push:
 branches:
  - main

jobs:
 build:
 runs-on: macos-latest
 steps:
  - name: Checkout code
    uses: actions/checkout@v4
  
  - name: Install dependencies
    run: bundle install

  - name: Install CocoaPods
    run: bundle exec pod install
  
  - name: Run Fastlane
    run: bundle exec fastlane beta
    env:
      APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
      MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}

当前报错 #

Error: "No profiles for 'com.example.app' were found"

已尝试的解决方法 #

• 确认Match仓库包含最新的配置文件和证书；
• 验证已传递正确的APP_STORE_CONNECT_API_KEY及其他密钥。

疑问 #

1. 导致该签名问题的原因是什么？
2. 如何正确配置Fastlane与GitHub Actions以构建并部署iOS应用至TestFlight？
3. 有哪些排查GitHub Actions中签名流程的技巧或步骤？

一、签名失败的常见原因 #

1. Match环境/类型不匹配：Match默认使用development环境，TestFlight需要appstore或adhoc类型的配置文件，若未指定会导致找不到对应配置。
2. Bundle ID不一致：Fastfile、Xcode项目配置中的Bundle ID，与Match仓库里配置文件的Bundle ID存在拼写或格式差异。
3. Match仓库权限缺失：GitHub Actions Runner无权限访问私有Match仓库，比如未配置SSH密钥或HTTPS凭证。
4. Xcode签名配置冲突：Xcode开启了「自动管理签名」，或签名设置与Fastlane Match的配置不兼容。
5. API Key权限不足：APP_STORE_CONNECT_API_KEY缺少Provisioning Profiles: Read等必要权限，无法读取或管理配置文件。

二、正确配置Fastlane + GitHub Actions的步骤 #

1. 完善Fastfile的Match配置 #

在beta lane中明确指定Match的环境和类型，确保与Match仓库中的配置一致：

lane :beta do
  # TestFlight需指定appstore类型的配置文件
  match(type: "appstore", readonly: true)
  
  gym(
    scheme: "YourAppScheme",
    export_method: "app-store",
    export_options: {
      provisioningProfiles: {
        "com.example.app" => "match AppStore com.example.app" # 与Match生成的配置文件名称一致
      }
    }
  )
  
  pilot # 上传至TestFlight
end

2. 配置Match仓库访问权限 #

如果Match仓库是私有仓库，需在GitHub Secrets中添加SSH密钥，在Action中配置：

- name: Setup SSH for Match
  uses: webfactory/ssh-agent@v0.8.0
  with:
    ssh-private-key: ${{ secrets.MATCH_SSH_KEY }}

若使用HTTPS方式，添加MATCH_GIT_TOKEN到Secrets，在Fastfile中指定：

match(git_url: "https://#{ENV['MATCH_GIT_TOKEN']}@github.com/your-org/match-repo.git", type: "appstore")

3. 统一Xcode签名配置 #

• 关闭Xcode「自动管理签名」，或用Fastlane命令统一配置：

update_code_signing_settings(
  use_automatic_signing: false,
  code_sign_identity: "iPhone Distribution",
  team_id: "YOUR_TEAM_ID"
)

• 确认项目Bundle ID与Match中的配置完全一致，无拼写错误。

4. 补充GitHub Actions环境变量 #

添加必要的环境变量，确保Fastlane能获取完整配置：

- name: Run Fastlane
  run: bundle exec fastlane beta
  env:
    APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
    MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
    TEAM_ID: ${{ secrets.TEAM_ID }}
    MATCH_GIT_TOKEN: ${{ secrets.MATCH_GIT_TOKEN }} # HTTPS访问Match仓库时需要

三、排查GitHub Actions签名问题的技巧 #

1. 开启Fastlane详细日志：在Action的Run Fastlane步骤中添加FASTLANE_VERBOSE=1环境变量，输出完整签名流程日志：

env:
  FASTLANE_VERBOSE: 1
  # 其他环境变量...

2. 本地模拟CI环境测试：在本地终端设置与CI相同的环境变量，运行bundle exec fastlane beta，复现问题后更易排查。
3. 检查Match仓库配置文件：直接查看Match仓库中profiles/appstore/com.example.app.mobileprovision文件，确认Bundle ID、Team ID是否正确，以及配置文件是否未过期。
4. 验证API Key权限：在App Store Connect的「Users and Access」中，检查API Key是否拥有Provisioning Profiles读写权限及App Store Connect API访问权限。
5. 查看Xcode构建日志：在GitHub Actions日志中找到Xcode构建输出部分，获取更详细的签名错误细节（如配置文件过期、证书不匹配等）。
6. 添加调试步骤：在Action中加入步骤，列出当前签名证书和配置文件，确认Match是否正确下载了资源：

- name: List signing assets
  run: |
    security find-identity -v -p codesigning
    ls -la ~/Library/MobileDevice/Provisioning\ Profiles/

内容的提问来源于stack exchange，提问作者Sinnoor C