跳过主要内容
CapgoLogo
CI/CD

Automatic Capacitor Android build with GitHub actions

在5分钟内使用fastlane和GitHub Actions为您的AndroidCapacitor应用设置CI/CD管道

马丁·多纳迪尤

马丁·多纳迪尤

内容营销人员
Automatic Capacitor Android build with GitHub actions

在设置 CI/CD 流程中，Capacitor 应用的配置可能会比较复杂和耗时。以下是您需要了解的内容：

我们现在推荐使用 Capgo 构建与 Capgo CLI 用于本地 Capacitor 构建。 本 Fastlane 指南保留用于维护现有 GitHub Actions pipeline 的团队，但新 Android 构建应使用 Capgo CLI 以避免维护 Fastlane、Gradle 运行器、keystore 和上传脚本。

前提条件

开始之前，您需要设置：

  • 一个具有管理员权限的 GitHub 账户
  • 您的应用已经在 Google Play Store 上发布并正确签名
  • Android 签名密钥和 keystore 文件
  • Google Cloud Console 项目，已启用 Play Store API
  • 具有适当权限的服务账户
  • 了解GitHub Actions工作流程
  • 了解Fastlane配置
  • 维护和调试管道所需的时间

Capgo Build通过Capgo来实现CI/CD

跳过Fastlane、Gradle runner、keystore和upload-script的维护 Capgo Build 从您的CI/CD管道中运行已有的签名原生Android构建：

  • 与您的管道兼容: Trigger Capgo Build from GitHub Actions, GitLab CI, Jenkins, or local scripts after your web build and npx cap sync.
  • 从CI密钥中签名：将Android密钥库、密钥别名、密码和Play Console服务账户JSON保存在您的CI密钥中
  • No native runner upkeep: Capgo Build 提供维护的 Android 构建环境，因此您不需要管理 SDK 镜像、Gradle 缓存问题或 Fastlane 通道。
  • Artifacts and submission: 下载已签名的 artifacts 用于 QA 或通过 Capgo CLI 提交发布版本。

Pricing

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

设置 Capgo Build 在 CI/CD

手动设置指南

以下是您需要做的事情：

GitHub Actions Pricing

价格GitHub动作

GitHub动作提供基于您的仓库类型的免费分钟数：

  • 公共仓库：每月2,000分钟
  • 私有仓库：每月2,000分钟（Linux 运行器）

对于私有项目，成本约为每分钟 $0.008。典型的构建时间为 3-5 分钟。

手动设置步骤

  1. 创建 Android Keystore
  2. 设置 Google Play 服务帐号
  3. 设置 Fastlane
  4. 配置GitHub机密
  5. 创建GitHub动作工作流

1. 创建 Android Keystore

在发布 Android 应用之前，您需要创建一个 keystore 文件。这是一个一次性的设置过程。

使用 keytool 生成 Keystore

在您的终端中运行以下命令：

keytool -genkey -v -keystore my-release-key.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

您将会被要求输入：

  • Keystore 密码: 选择一个强大的密码（您将需要它作为 KEYSTORE_STORE_PASSWORD)
  • Key 密码: 选择一个强大的密码（您将需要它作为 KEYSTORE_KEY_PASSWORD)
  • 您的姓名、组织等: 填写您的详细信息

重要注意事项

  • 请务必安全保存这些值:

    • 密钥库文件位置（例如， my-release-key.keystore)
    • 密钥别名（例如， my-key-alias] - 你需要这个作为 KEYSTORE_KEY_ALIAS
    • 密钥库密码 - 你需要这个作为 KEYSTORE_STORE_PASSWORD
    • 密钥密码 - 你需要这个作为 KEYSTORE_KEY_PASSWORD

  • 备份密钥库文件: 如果你丢失了它，你无法更新你的发布应用

  • 保密: 不要将密钥库文件提交到git

  • 安全存储: 在安全的位置保留多个备份

备选方案：使用现有密钥库

如果您已经发布了您的应用程序，则必须使用最初使用的同一个keystore。您可以在以下位置找到它：

  • 在您第一次构建应用程序的本地机器上
  • 在Play Console → 设置 → 应用签名（如果使用Google Play App Signing）

2. 设置Google Play服务帐户

为了允许GitHub Actions 将构建上传到Google Play，您需要一个服务帐户。

步骤2.1：创建Google Cloud项目

  1. 前往 Google Cloud控制台
  2. 创建新项目或选择现有项目
  3. 注意项目ID

步骤2.2：启用Google Play开发者API

  1. 在Google Cloud控制台中，前往 APIs & Services → 库
  2. 搜索 “Google Play Android Developer API”
  3. 点击 启用

步骤 2.3: 创建服务帐号

  1. 前往 IAM & Admin → 服务帐号
  2. 点击 创建服务帐号
  3. 输入详细信息：
    • Name: github-actions-uploader
    • 描述: “为GitHub Actions上传构建的服务帐户”
  4. 点击 创建并继续
  5. 跳过角色赋予（点击 继续,然后 完成)

步骤 2.4：创建服务帐户密钥

  1. 点击新创建的服务帐户
  2. 前往 密钥 选项卡
  3. 点击 添加密钥 → 创建新密钥
  4. 选择 JSON 格式
  5. 点击 创建
  6. 一个 JSON 文件将下载 - 请安全保存，这样你以后会需要它__CAPGO_KEEP_0__

步骤 2.5: 在 Play Console 中授权

  1. 前往 Google Play Console
  2. 前往 设置 → API 授权
  3. 在 服务帐号, 点击 授权 为您的服务帐号
  4. 在 App 权限 标签，添加您的应用
  5. 在 账户权限 标签，授予这些权限：
    • 查看应用信息和下载批量报告（只读）
    • 创建、编辑和删除草稿应用
    • 将应用发布到测试跟踪
    • 将应用发布到生产、排除和其他跟踪
  6. 点击 邀请用户
  7. 点击 发送邀请

步骤 2.6：验证 JSON 密钥

下载的 JSON 文件应该像这样：

{
  "type": "service_account",
  "project_id": "your-project-id",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "github-actions-uploader@your-project-id.iam.gserviceaccount.com",
  "client_id": "...",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "..."
}

您将在 GitHub 秘密设置步骤中将其转换为 base64。

3. 设置 Fastlane

在项目根目录创建一个 fastlane 文件夹，并添加一个 Fastfile 内容如下：

default_platform(:android)

KEYSTORE_KEY_ALIAS = ENV["KEYSTORE_KEY_ALIAS"]
KEYSTORE_KEY_PASSWORD = ENV["KEYSTORE_KEY_PASSWORD"]
KEYSTORE_STORE_PASSWORD = ENV["KEYSTORE_STORE_PASSWORD"]

platform :android do
    desc "Deploy a beta version to the Google Play"
    private_lane :verify_changelog_exists do |version_code: |
      changelog_path = "android/metadata/en-US/changelogs/#{version_code}.txt"
      UI.user_error!("Missing changelog file at #{changelog_path}") unless File.exist?(changelog_path)
      UI.message("Changelog exists for version code #{version_code}")
    end

    private_lane :verify_upload_to_staging do |version_name: |
      UI.message "Skipping staging verification step"
    end
    
    lane :beta do
        keystore_path = "#{Dir.tmpdir}/build_keystore.keystore"
        File.write(keystore_path, Base64.decode64(ENV['ANDROID_KEYSTORE_FILE']))
        json_key_data = Base64.decode64(ENV['PLAY_CONFIG_JSON'])
        
        # Get previous build number and increment
        previous_build_number = google_play_track_version_codes(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            track: "internal",
            json_key_data: json_key_data,
        )[0]
        current_build_number = previous_build_number + 1
        sh("export NEW_BUILD_NUMBER=#{current_build_number}")
        
        # Build the app
        gradle(
          task: "clean bundleRelease",
          project_dir: 'android/',
          print_command: false,
          properties: {
            "android.injected.signing.store.file" => "#{keystore_path}",
            "android.injected.signing.store.password" => "#{KEYSTORE_STORE_PASSWORD}",
            "android.injected.signing.key.alias" => "#{KEYSTORE_KEY_ALIAS}",
            "android.injected.signing.key.password" => "#{KEYSTORE_KEY_PASSWORD}",
            'versionCode' => current_build_number
          })
        
        # Upload to Play Store
        upload_to_play_store(
            package_name: ENV['DEVELOPER_PACKAGE_NAME'],
            json_key_data: json_key_data,
            track: 'internal',
            release_status: 'completed',
            skip_upload_metadata: true,
            skip_upload_changelogs: true,
            skip_upload_images: true,
            skip_upload_screenshots: true,
        )
    end
end

4. 配置 GitHub 秘密

现在您已经拥有您的 keystore 和服务帐户 JSON，需要安全地将它们存储在 GitHub 中。

步骤 4.1：访问 GitHub 秘密

  1. 前往您的仓库在 GitHub
  2. 点击 设置 → 密钥和变量 → 操作
  3. 点击 新建仓库密钥

步骤 4.2: 添加必需密钥

逐一添加这些密钥:

PLAY_CONFIG_JSON

  1. 取出步骤 2.4 下载的服务账户 JSON 文件
  2. 将其转换为 base64:

在 macOS/Linux 上:

base64 service_account_key.json | pbcopy

On Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("service_account_key.json")) | Set-Clipboard
  1. 创建一个名为 PLAY_CONFIG_JSON 并粘贴 base64 字符串

__CAPGO_KEEP_0__

  1. 将您的 keystore 转换为 base64:

On macOS/Linux:

base64 my-release-key.keystore | pbcopy

On Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("my-release-key.keystore")) | Set-Clipboard
  1. 创建一个名为 ANDROID_KEYSTORE_FILE 并粘贴 base64 字符串

__CAPGO_KEEP_1__

创建一个名为您在生成 keystore 时使用的密钥别名 (例如 my-key-alias)

创建一个名为您在生成 keystore 时使用的密钥密码 (例如

使用生成密钥库时设置的密码创建一个新的密钥

__CAPGO_KEEP_0__

使用生成密钥库时设置的密钥库密码创建一个新的密钥

开发者包名

使用您的应用程序包名创建一个新的密钥（例如， com.example.app)

您可以在 android/app/build.gradle 下找到 applicationId

步骤 4.3：验证所有密钥

确保您已配置以下 6 个密钥：

  • ✅ PLAY_CONFIG_JSON
  • ✅ ANDROID_KEYSTORE_FILE
  • ✅ 密钥库别名
  • ✅ 密钥库密码
  • ✅ 密钥库存储密码
  • ✅ 开发者包名

5. 创建 GitHub Actions Workflow

创建 .github/workflows/build-upload-android.yml:

name: Build and Deploy Android App

on:
  push:
    tags:
      - '*'

jobs:
  build_android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
          cache: npm
          
      - name: Install dependencies
        run: npm ci
        
      - name: Cache Gradle
        uses: actions/cache@v5
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            ${{ runner.os }}-gradle-
            
      - name: Build app
        run: npm run build
        
      - name: Sync Capacitor
        run: npx cap sync
        
      - name: Setup Java
        uses: actions/setup-node@v5
        with:
            distribution: 'zulu'
            java-version: '17'
            
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
          bundler-cache: true
          
      - name: Run Fastlane
        uses: maierj/fastlane-action@v3.1.0
        env:
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          DEVELOPER_PACKAGE_NAME: ${{ secrets.DEVELOPER_PACKAGE_NAME }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
        with:
          lane: android beta
          
      - name: Upload artifact
        uses: actions/upload-artifact@v2
        with:
          name: android-release
          path: ./android/app/build/outputs/bundle/release/app-release.aab
          retention-days: 10

如何工作

  1. 创建一个 Git 标签来触发工作流
  2. GitHub Actions 构建您的应用
  3. Fastlane 将其上传到 Google Play beta 频道
  4. 您的应用将自动更新

构建时间和成本

  • 构建时间：3-5 分钟
  • 私有仓库的成本：约每次构建 $0.04
  • 开源项目免费

CI/CD 配置指南

替代 CI/CD 平台

实时更新 & 部署

资源

Keep going from Automatic Capacitor Android build with GitHub actions

如果您正在使用 自动Capacitor Android构建与GitHub动作 来规划CI/CD自动化，连接它与 Capgo CI/CD 为Capgo CI/CD中的产品工作流程 Capgo 原生构建 为Capgo 原生构建中的产品工作流程 Capgo 集成 为Capgo 集成中的产品工作流程 CI/CD集成 CI/CD集成的实现细节 GitHub 动作集成 关于在GitHub Actions Integration中实现细节。

实时更新 Capacitor 应用

当 web 层 bug 活跃时，通过 Capgo 将修复推送，而不是等待几天的应用商店审批。用户在后台接收更新，而本机更改保持在正常审批路径中。

立即开始

博客最新文章

Capgo 为您提供了创建真正专业的移动应用所需的最佳见解。

Capacitor 应用中的双向通信
开发 移动 +1
2025年4月26日

Capacitor 应用中的双向通信

避免 5 个常见的 OTA 更新错误
开发 安全 +1
2025年4月13日

5种避免OTA更新的常见错误

5种移动应用程序实时更新的安全最佳实践
开发 移动 +1
2025年1月14日

5种移动应用程序实时更新的安全最佳实践

查看我们的博客