自动上传 App 与 CI/CD 集成指南

您可以在构建完成后自动将安装包上传到蒲公英，获取下载链接和二维码，再交给测试人员安装。本文汇总常见接入方式，帮助您选择工具并完成基本集成；完整参数和平台配置可继续查看对应专题文档。

自动上传的完整流程

构建、签名并生成安装包 → 上传到蒲公英 → 等待发布处理完成 → 获取下载链接或二维码 → 分发给测试人员。

您的开发工具或 CI/CD 系统负责构建和签名，蒲公英负责接收安装包、处理发布并提供下载分发。请先确保构建步骤已经生成可用的安装包，再执行上传步骤。

选择适合您的接入方式

如果您还没有确定工具，可以从 CLI 开始；需要将上传深度集成到自己的系统时，选择快速上传 API。多语言示例是快速上传 API 的实现参考，Shell 示例也是其中一种。

接入前的准备

1. 准备已经构建并签名的安装包。快速上传 API 和 CLI 支持 .ipa、.apk、.hap；各插件支持的类型以对应工具说明为准。HarmonyOS 的证书及依赖文件要求见 HarmonyOS 内测分发。
2. 登录蒲公英，在 API 信息页面 获取 API Key。
3. 在 CI/CD 的密钥或凭据管理中保存 API Key，并注入上传步骤。CLI、Shell 示例、MCP、Fastlane 插件和 Gradle 插件可以使用环境变量 PGYER_API_KEY；其他插件请按其参数要求配置。
4. 确认上传步骤能读取安装包并访问蒲公英 API 及接口返回的上传地址。构建和上传分属不同 Job 时，需要先传递或下载构建产物。

请勿将真实 API Key 写入 Git 仓库或输出到构建日志。日常自动上传使用流水线提供的密钥，无需每次交互式登录。

快速开始：通过 CLI 上传

在满足 CLI 环境要求 的机器上安装工具：

npm install -g @pgyer/cli

在 CI/CD 中配置好 PGYER_API_KEY 后，执行：

pgyer upload ./app-release.apk

将路径替换为您的实际安装包路径；路径包含空格时请加引号。CLI 默认等待蒲公英处理完成；需要供后续程序读取结果时，可添加 --json。本地开发也可以先运行 pgyer auth login 完成认证，再执行上传。

例如，在已有构建步骤之后添加以下 Shell 命令：

set -eu
: "${PGYER_API_KEY:?请先在 CI/CD 中配置 PGYER_API_KEY}"
test -f ./app-release.apk
pgyer upload ./app-release.apk

该片段假设 CLI 已安装，且安装包已放入当前工作目录。正式流水线中建议固定经过验证的 CLI 版本。更多参数请运行 pgyer upload --help，或查看 CLI 文档。

如果您使用现有 Shell 环境，可将 Shell 示例 下载并纳入自己的脚本目录。按照示例说明准备依赖、配置 PGYER_API_KEY 后执行：

bash ./shell-demo/pgyer_upload.sh ./app-release.apk

通过快速上传 API 接入自己的系统

新接入建议使用 快速上传 API，核心流程包含三个步骤：

1. 获取上传凭证：调用 getCOSToken，取得上传地址 endpoint、文件标识 key 和签名参数。
2. 上传安装包：按接口说明，将文件和签名参数以 multipart/form-data 提交到返回的 endpoint。请使用响应中的地址和参数。
3. 查询发布结果：使用第一步返回的 key 作为查询参数 buildKey，调用 buildInfo，等待发布完成并取得应用信息。

代码示例仓库 提供可运行的实现参考：

具体依赖、调用参数和错误处理见各目录说明；完整接口字段见 上传与发布 API。

接入现有 CI/CD 工具

Jenkins

使用 Jenkins 插件，可在 Pipeline 中调用 pgyerUpload，或在自由风格任务中添加“上传到蒲公英（PGYER）”构建步骤。插件在执行构建的节点上上传，API Key 保存在 Jenkins 凭据中，上传后返回下载页地址和二维码，可用于后续步骤。

Fastlane

在项目中安装蒲公英插件：

fastlane add_plugin pgyer

在已经完成打包配置的 lane 中，紧接打包步骤加入：

pgyer(api_key: ENV.fetch("PGYER_API_KEY"))

安装包路径、更新说明和安装方式等配置见 Fastlane 文档 及 插件仓库。

Gradle

在 Android 应用模块中添加 Gradle 插件：

plugins {
    id("com.android.application")
    id("com.pgyer.upload") version "1.0.0"
}

在 CI/CD 中配置好 PGYER_API_KEY 后执行：

./gradlew uploadPgyerRelease

插件会先构建对应变体的 APK 再上传，下载页地址写入应用模块的 build/outputs/pgyer/release.json。也可以用 PgyerUploadTask 上传 ipa 和 hap 文件，详见 Gradle 插件文档。

GitHub Actions

在构建步骤之后添加 蒲公英上传 Action，并在仓库 Secrets 中保存 PGYER_API_KEY：

- name: Upload to Pgyer
  id: pgyer
  uses: PGYER/pgyer-upload-app-action@v2
  with:
    _api_key: ${{ secrets.PGYER_API_KEY }}
    appFilePath: app/build/outputs/apk/release/app-release.apk
    buildUpdateDescription: Build ${{ github.run_number }}

Action 支持 apk、ipa 和 hap 安装包，上传失败时这一步会失败。后续步骤可以使用 steps.pgyer.outputs.appPgyerURL（下载页地址）和 steps.pgyer.outputs.buildQRCodeURL（二维码地址），全部参数和输出见 Action 说明。仍在使用 v1.3 的工作流请改为 @v2。

也可以在已有工作流中调用 CLI。以下片段放在同一个 Job 的构建步骤之后，假设已准备好 CLI 所需的 Node.js 环境：

- name: Install Pgyer CLI
  run: npm install -g @pgyer/cli

- name: Upload to Pgyer
  env:
    PGYER_API_KEY: ${{ secrets.PGYER_API_KEY }}
  run: pgyer upload ./app-release.apk

请替换实际安装包路径，并选择可以访问该 Secret 的发布触发条件。CLI 安装版本可按团队验证结果固定。

GitLab CI 与其他平台

在构建完成后的 Job 或步骤中安装 CLI、注入 PGYER_API_KEY 并执行上传命令即可。GitLab CI 中可以通过 CI/CD Variables 保存密钥，通过 artifacts 将安装包传递给上传 Job。

接入其他系统时也遵循相同流程：准备运行环境、取得构建产物、配置认证、执行上传、检查结果。支持执行脚本或发出 HTTP 请求的平台都可以按此方式集成。

通过 AI 助手上传：MCP 与 Agent Skill

MCP：让 AI 调用上传和查询工具

蒲公英 MCP 将上传安装包、查询应用列表、按短链接查询应用信息等能力提供给兼容的 AI 客户端。

按照 MCP 文档完成客户端配置，并确保工具运行环境能读取安装包后，您可以向 AI 助手提出这样的请求：

Agent Skill：指导 AI 完成接入流程

蒲公英 Agent Skill 提供上传方式选择、结果整理、CI/CD 示例和排错指引。可通过以下命令安装，再按专题文档配置认证：

npx skills add PGYER/pgyer-skill

您既可以让 AI 上传已有安装包，也可以让它协助配置流水线：

MCP 提供可调用的工具，Skill 指导 AI 如何选择和组合操作，两者可以配合使用。当前 Skill 优先使用可用的 MCP，也提供 Shell 脚本和 API 接入路径，具体行为见 Skill 仓库。

AI 生成的流水线配置需要结合项目的构建命令、产物路径和触发条件检查并运行验证。配置完成后，后续自动上传由流水线执行。

上传结果与常用发布设置

快速上传 API 发布成功时，可从 buildInfo 的 data 中取得以下信息；CLI 和各插件的输出形式以各自文档为准。

拿到结果后，可将下载地址写入构建摘要，或交给现有通知步骤发送给测试人员。更多通知配置见 外部集成与通知相关文档。

常用发布设置包括更新说明、公开或密码安装、邀请安装，以及指定已创建的渠道。快速上传 API 对应参数为 buildUpdateDescription、buildInstallType、buildPassword、buildChannelShortcut；各工具的参数名称可能不同，请查看专题说明。

常见问题

没有对应平台的专用插件，能否接入？

可以。只要系统能执行命令或调用 HTTP 接口，就可以使用 CLI、Shell 或快速上传 API。上传步骤需要能够读取安装包并访问相关服务。

上传失败或超时应该如何处理？

先检查安装包路径、读取权限、API Key 和网络，再查看工具或 API 返回的错误说明。查询发布结果时，只对文档说明的处理中状态继续轮询；遇到明确失败应停止并处理原因。超时后先核实发布结果，再决定是否重新上传，避免重复提交。

上传成功后，安装包是否可以一直保留？

自动上传同样适用 账户容量与历史版本清理规则。容量超额时按主账户策略处理，空间不足时 API 可能返回失败结果。请检查最终发布状态，并在 CI/CD 产物库或归档系统中保存仍需长期使用的安装包。

更多开发工具

• Android Studio 插件：在 IDE 内手动选择并上传 APK。
• 第三方插件汇总：社区维护的 Flutter 打包发布工具、Gradle 插件等，使用前请核对具体项目的维护状态和兼容性。

各专题文档继续提供完整安装步骤、参数和示例，您可以根据选型表进入对应页面。