自动化 Capacitor IOS 构建使用 GitHub 动作与证书

设置Capacitor应用的CI/CD可能会很复杂和耗时。以下是您需要了解的内容：

推荐新建：使用Capgo Build

我们现在建议使用 Capgo Build与CapgoCLI 为原生Capacitor构建。 本Fastlane指南保留供维护现有GitHub Actions管道的团队使用，但新iOS构建应使用Capgo CLI，免去维护Fastlane、Xcode运行器、证书和上传脚本的麻烦。

Capgo构建由Capgo提供

跳过Fastlane、Xcode运行器、证书、配置文件和上传脚本的维护。 Capgo构建 __CAPGO_KEEP_0__构建从您的现有CI/CD管道中运行签名的原生iOS构建：

与您的管道兼容: 在Capgo Build触发器之后，触发Capgo Build从GitHub Actions、GitLab CI、Jenkins或本地脚本中 npx cap sync.
从CI密钥签名: 在您的CI密钥中保留App Store Connect密钥、证书、配置文件、密码和团队ID。
无原生运行器维护: Capgo Build提供维护的Apple构建环境，因此您不必管理macOS运行器、Xcode图像或Fastlane通道。
artifacts 和提交: 下载已签名的 artifacts 进行 QA 或通过 Capgo CLI 提交发布 builds。

定价

Capgo 计划从 $12/月开始
包括 OTA 更新和约 15 个本机构建/月
额外的构建分钟通过信用额度按分钟计费

设置 Capgo Build 在 CI/CD 中

手动设置指南

以下是您需要做的事情:

使用 Fastlane 和 GitHub Actions 和证书进行 iOS 的持续交付

先决条件

在继续教程之前：

确保你在开发机器上安装了Fastlane 已安装在开发机器上安装了Fastlane
确保你是iOS开发者计划的成员

关于价格的重要信息

价格GitHub动作

https://github.com/features/actions

服务是‘免费的，直到达到限制，取决于所选机器 我们将使用一个
macOS 计划机器，截图中可以看到其价格和限制（截图创建时的价格，可能会在未来发生变化）

警告了需求和价格后，让我们继续。

注意：在这篇文章中，我假设您已经在 App Store Connect 中创建了应用。重要信息将由 Fastlane 复制！

本教程中您将学习到的内容

本教程中您需要遵循的步骤

使用 App Store Connect API 和 Fastlane
- 需求：
  - 创建 App Store Connect API 密钥
  - 使用 App Store Connect API 密钥
复制 Fastlane 文件
配置 GitHub 动作

1. 使用 App Store Connect API 和 Fastlane

自2021年2月起，所有用户登录App Store Connect都需要使用两步验证或两因素验证。这一额外的安全层对于您的Apple ID有助于确保您是唯一能够访问您的账户的人。
从 Apple支持

要求

为了让Fastlane能够使用App Store ConnectAPI上传您的应用，您需要提供以下三个事项:

颁发者ID
密钥ID
密钥文件或密钥内容

获取App Store ConnectAPI密钥

要生成密钥，您必须在App Store Connect中具有管理员权限。如果您没有该权限，可以将相关人员指向本文。

登录到 App Store Connect.
选择用户和访问.

App Store Connect 用户访问

3 — 选择 Integration 标签

App Store Connect API Integration

点击生成 API 密钥或添加 (+) 按钮

App Store Connect API 密钥创建

输入密钥的名称。该名称仅供您参考，不是密钥的一部分

App Store Connect API 密钥创建名称

6 — 在访问下，选择密钥的角色。密钥的角色与您的团队中用户的角色相同。请参见角色权限. 我们建议您选择 应用管理者.

点击生成。

一个API密钥的访问权限不能被限制到特定的应用。

新密钥的名称、密钥ID、下载链接和其他信息将出现在页面上。

App Store Connect下载密钥

您可以在这里获取所有三个必要的信息。
<1>问题ID。 (APPLE_ISSUER_ID 密钥)
<2>密钥ID。 (APPLE_KEY_ID 密钥)
点击“下载 API 密钥”来下载您的 API 私钥。下载链接仅在私钥尚未下载时才会出现。苹果不会保留私钥的副本。因此，您只能下载一次。

🔴 请将您的私钥存储在安全的地方。您不应共享您的密钥、将密钥存储在 code 仓库中或将密钥包含在客户端 code 中。

使用 App Store Connect API 密钥

下载的 API 密钥文件（p8 文件）、密钥 ID 和颁发者 ID 是创建授权 JWT 令牌所需的信息。有多种方法可以将此信息传递给 Fastlane。我选择使用 Fastlane 的新动作 app_store_connect_api_key您可以在 Fastlane 文档中学习其他方法。我展示此方法，因为我认为它是与大多数 CI 工作最方便的方法，即您可以设置环境变量。

请将下载的 p8 文件转换为 Base64 并将其存储为一个秘密（APPLE_KEY_CONTENT).

base64 -i APPLE_KEY_CONTENT.p8 | pbcopy

现在我们可以使用 API 密钥来管理 App Store Connect，太棒了！

2. 证书

打开 XCode 并前往设置 > 账号 > Apple ID > 团队选择您的团队。

Code 签名身份

点击 管理证书.

如果您尚未创建证书，请创建新证书。

点击 + 并选择 苹果分发

苹果分发

然后您需要前往钥匙串下载证书作为 .p12 文件。

要做到这一点，您需要前往钥匙串切换到登录钥匙串 然后选项卡.

我的证书

然后您可以选择要下载的证书。 (通过证书的日期查找 ) 导出.

选择文件格式 个人信息交换 (.p12).

将下载证书作为 .p12 文件。

请在终端中打开文件并使用以下命令将其转换为 Base64:

base64 -i BUILD_CERTIFICATE.p12 | pbcopy

将成为您的 BUILD_CERTIFICATE_BASE64 密钥。另外，当被询问时，请提供证书的密码。这将是您的 P12_PASSWORD 密钥。

3. 配置文件

打开苹果开发者然后选择正确的团队。

然后创建一个新的配置文件，点击 +

创建一个新的配置文件

并选择 App Store Connect.

选择 App Store Connect

然后您需要选择正确的应用程序，注意不能使用通配符否则签名会失败。

选择正确的应用程序

选择您之前创建的正确证书（查找有效期日期，应该与今天相同的日期和月份），并点击继续.

选择正确的证书

最后输入配置文件的名称并点击生成.

将该名称用作在Fastlane中的配置文件标识，值为 APPLE_PROFILE_NAME.

生成配置文件

您可以下载配置文件作为一个 .mobileprovision 文件。

下载配置文件

请将配置文件转换为Base64并将其存储为一个秘密（BUILD_PROVISION_PROFILE_BASE64).

base64 -i BUILD_PROVISION_PROFILE.mobileprovision | pbcopy

4. 复制Fastlane文件

Fastlane是一个用Ruby编写的库，用于自动化移动开发的常见任务。使用Fastlane，您可以配置自定义的“道线”（lanes），这些道线包含一系列的“动作”（actions），这些动作执行您通常使用Android Studio执行的任务。您可以在Fastlane中做很多事情，但在本教程中，我们将仅使用核心动作的一小部分。

在您的Capacitor/Ionic项目的根目录下创建一个Fastlane文件夹，并在其中添加一个Fastfile文件：

文件夹： <project-root>/fastlane/
文件： <project-root>/fastlane/Fastfile

本级别与 package.json, capacitor.config.*，并且 ios/ 文件夹相同。不要在 ios/App/.

platform :ios do
  desc 'Export ipa and submit to TestFlight'
  lane :beta do
    keychain_info = { keychain_name: "ios-build-#{Time.now.to_i}.keychain", keychain_password: SecureRandom.uuid }
    
    begin
      setup_signing(keychain_info)
      bump_build_number
      build_app_with_signing(keychain_info)
      submit_to_testflight
    ensure
      cleanup_keychain(keychain_info)
    end
  end

  private_lane :setup_signing do |options|
    create_keychain(
      name: options[:keychain_name],
      password: options[:keychain_password],
      unlock: true,
      timeout: 0,
      lock_when_sleeps: false, 
      add_to_search_list: true
    )
    import_cert(options)
    install_profile
    update_project_settings
  end

  lane :bump_build_number do
		file = File.read('../package.json')
		data_hash = JSON.parse(file)
		api_key = app_store_connect_api_key(
      key_id: ENV['APPLE_KEY_ID'],
      issuer_id: ENV['APPLE_ISSUER_ID'],
      key_content: ENV['APPLE_KEY_CONTENT'],
      is_key_content_base64: true,
      duration: 1200,
      in_house: false
    )
		build_num = app_store_build_number(
      api_key: api_key,
			app_identifier: ENV['BUNDLE_IDENTIFIER'],
			live: false
    )
		build_num = build_num + 1
		UI.message("Bumped build number to #{build_num}")
		increment_build_number(
			build_number: build_num,
			xcodeproj: "./ios/App/App.xcodeproj",
			skip_info_plist: true
		)
	end

  private_lane :import_cert do |options|
    cert_path = "#{Dir.tmpdir}/build_certificate.p12"
    File.write(cert_path, Base64.decode64(ENV['BUILD_CERTIFICATE_BASE64']))
    import_certificate(
      certificate_path: cert_path,
      certificate_password: ENV['P12_PASSWORD'] || "",
      keychain_name: options[:keychain_name],
      keychain_password: options[:keychain_password],
      log_output: true
    )
    File.delete(cert_path)
  end  
  
  private_lane :cleanup_keychain do |options|
    delete_keychain(
      name: options[:keychain_name]
    )
  end  

  private_lane :install_profile do
    profile_path = "#{Dir.tmpdir}/build_pp.mobileprovision"
    File.write(profile_path, Base64.decode64(ENV['BUILD_PROVISION_PROFILE_BASE64']))
    UI.user_error!("Failed to create provisioning profile at #{profile_path}") unless File.exist?(profile_path)
    ENV['PROVISIONING_PROFILE_PATH'] = profile_path
    install_provisioning_profile(path: profile_path)
    File.delete(profile_path)
  end

  private_lane :update_project_settings do
    update_code_signing_settings(
      use_automatic_signing: false,
      path: "./ios/App/App.xcodeproj",
      code_sign_identity: "iPhone Distribution",
      profile_name: ENV['APPLE_PROFILE_NAME'],
      bundle_identifier: ENV['BUNDLE_IDENTIFIER'],
      team_id: ENV['APP_STORE_CONNECT_TEAM_ID']
    )
    update_project_team(
      path: "./ios/App/App.xcodeproj",
      teamid: ENV['APP_STORE_CONNECT_TEAM_ID']
    )
  end

  private_lane :build_app_with_signing do |options|
    unlock_keychain(
      path: options[:keychain_name],
      password: options[:keychain_password],
      set_default: false
    )
    build_app(
      workspace: "./ios/App/App.xcworkspace",
      scheme: "App",
      configuration: "Release",
      export_method: "app-store",
      output_name: "App.ipa",
      export_options: {
        provisioningProfiles: {
          ENV['BUNDLE_IDENTIFIER'] => ENV['APPLE_PROFILE_NAME']
        }
      },
      xcargs: "-verbose",
      buildlog_path: "./build_logs",
      export_xcargs: "-allowProvisioningUpdates",
    )
  end   

  private_lane :submit_to_testflight do
    api_key = app_store_connect_api_key(
      key_id: ENV['APPLE_KEY_ID'],
      issuer_id: ENV['APPLE_ISSUER_ID'],
      key_content: ENV['APPLE_KEY_CONTENT'],
      is_key_content_base64: true,
      duration: 1200,
      in_house: false
    )
    pilot(
      api_key: api_key,
      skip_waiting_for_build_processing: true,
      skip_submission: true,
      distribute_external: false,
      notify_external_testers: false,
      ipa: "./App.ipa"
    )
  end
end

5. 配置机密

GitHub .env Actions 使用您在下一步中配置的仓库机密。您只需要一个本地

文件，如果您想在自己的机器上运行或测试 Fastlane。 <project-root>/fastlane/.env 对于本地测试，请在 Fastfile旁边创建 fastlane/.env 。不要将此文件提交。将 .gitignore 添加到您的

APP_STORE_CONNECT_TEAM_ID=UVTJ336J2D
BUNDLE_IDENTIFIER=ee.forgr.testfastlane
# See previous section for these secrets
BUILD_CERTIFICATE_BASE64=
BUILD_PROVISION_PROFILE_BASE64=
APPLE_KEY_ID=
APPLE_ISSUER_ID=
APPLE_KEY_CONTENT=
P12_PASSWORD=
APPLE_PROFILE_NAME=

首先（或验证它已经被忽略）。以下是示例：

前往开发者中心并滚动到底部到 Membership details 部分。 Team ID 是您需要在 APP_STORE_CONNECT_TEAM_ID 密钥

app-store-connect-team-id

获取BUNDLE_IDENTIFIER
打开Xcode App 双击项目导航器中的
然后单击标签 Signing and Capabilities
复制此值： Bundle identifier。这个值需要在 BUNDLE_IDENTIFIER 中设置。

6. 构建处理

在GitHub Actions中 您根据CI/CD工作流程运行的分钟数而被计费。根据我的经验，构建在App Store Connect中处理需要约10-15分钟。 对于私有项目，估算的每次构建成本可能高达

$0.08/分钟 x 15 分钟 = $1.2 ，或更多，取决于您的项目的配置和依赖项。如果您对私有项目的成本有所担忧，可以设置

If you’re concerned about costs for private projects, you can set skip_waiting_for_build_processing 到 true。通过这种方式，可以节省构建分钟，因为不需要等待App Store Connect处理完成。

然而，这种优化方式有一个缺点：你需要手动更新你的应用的合规信息在App Store Connect中，才能将构建分发给用户。

This optimization is mainly useful for private projects where build minutes cost money. For public/free projects, the build minutes are free so there’s no need to enable this setting. See GitHub’s 的价格页面获取更多详细信息。

7. Setup GitHub Actions

Configure GitHub secrets

请从 .env file and paste them into the GitHub repository secrets.

的仓库密钥中。前往 > 密钥和变量 > 动作 > 新仓库密钥

2. BUILD_CERTIFICATE_BASE64 证书（Base64编码）

3. BUILD_PROVISION_PROFILE_BASE64 应用程序配置文件（Base64编码）

4. BUNDLE_IDENTIFIER 应用程序的包标识符

5. APPLE_KEY_ID — App Store Connect API Key 🔺Key ID

6. APPLE_ISSUER_ID — App Store Connect API Key 🔺Issuer ID

7. APPLE_KEY_CONTENT —— App Store Connect API Key 🔺 Key content of .p8, 查看它

8. 配置 GitHub 工作流文件

创建一个 GitHub 工作流目录

cd .github/workflows

在文件夹内，创建一个名为 workflow 并添加以下内容。 build-upload-ios.yml此工作流应在每次 __CAPGO_KEEP_0__

name: Build source code on ios

on:
  push:
    tags:
      - '*'

jobs:
  build_ios:
    runs-on: macOS-latest
    steps:
      - uses: actions/checkout@v6
      - name: Set Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
      - name: Install dependencies
        id: install_code
        run: npm ci
      - name: Build
        id: build_code
        run: npm run build
      - uses: actions/cache@v5
        with:
          path: ios/App/Pods
          key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
          restore-keys: |
            ${{ runner.os }}-pods-
      - name: Sync
        id: sync_code
        run: npx cap sync
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
          bundler-cache: true
      - uses: maierj/fastlane-action@v3.1.0
        env:
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUNDLE_IDENTIFIER: ${{ secrets.BUNDLE_IDENTIFIER }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          BUILD_PROVISION_PROFILE_BASE64: ${{ secrets.BUILD_PROVISION_PROFILE_BASE64 }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
          APPLE_PROFILE_NAME: ${{ secrets.APPLE_PROFILE_NAME }}
        with:
          lane: ios beta
      - name: Upload release bundle
        uses: actions/upload-artifact@v6
        with:
          name: ios-release
          path: ./App.ipa
          retention-days: 10

This workflow should be triggered after each GitHub 后触发，如果您需要自动化标签，请参阅自动构建和发布与 __CAPGO_KEEP_0__ 动作 Automatic build and release with GitHub actions 首先.

然后，这个工作流程将拉取您的 NodeJS 依赖项，安装它们并构建您的 JavaScript 应用程序.

每次您发送新的提交时，测试版将在 TestFlight 中构建一个发布.

您的 App 不需要使用 Ionic，只需使用 Capacitor 基础即可，它可以使用旧的 Cordova 模块，但 Capacitor JS 插件应优先使用.

8. 触发工作流程

创建一个提交

制作一个提交，您应该在仓库中看到正在运行的工作流程.

触发工作流程

推送新的提交到分支 main 或者 development 触发工作流程。

使用以下提交开始

几分钟后，您的 App Store Connect 控制台中应该可以看到构建。

Testflight 控制台

9. 我可以从本地机器部署吗？

是的，您可以，而且非常方便。

您可以使用 Xcode 构建和签名您的应用，正如往常一样。

CI/CD 设置指南

自动 Capacitor Android 构建与 GitHub 动作 - 完成 Android CI/CD 设置
自动构建和发布与 GitHub 动作 - 全自动 CI/CD pipeline 教程
使用 GitHub Actions 管理开发和生产构建 - 环境管理
使用 Match 自动 Capacitor iOS 构建 - 使用 Fastlane Match 的另一种方法

CI/CD 平台的替代方案

使用 GitLab CI 构建 - GitLab 的替代方案
使用 CodeMagic 构建 - CodeMagic 的设置指南

实时更新和部署

Capgo 实时更新文档 - 为应用程序添加 OTA 更新
CI/CD Integration with Capgo - 将实时更新集成到管道中

感谢

本博客基于以下文章:

Keep going from Automatic Capacitor IOS build with GitHub actions with certificate

如果您正在使用 Automatic Capacitor IOS build with GitHub actions with certificate 为了计划CI/CD自动化，连接它与 Capgo CI/CD 为产品工作流程在Capgo CI/CD中 Capgo 原生构建为产品工作流程在Capgo 原生构建中 Capgo 集成 for the product workflow in Capgo Integrations, 为产品工作流程在__CAPGO_KEEP_0__ 集成中 CI/CD集成 GitHub Actions Integration for the implementation detail in GitHub Actions Integration.

自动Capacitor IOS构建与GitHub动作证书