Upload via Fastlane

Install and configure Pgyer's Fastlane plugin to upload the Android, iOS, and HarmonyOS builds Fastlane produces.

Fastlane is an automation tool for iOS and Android developers that strings together build, signing, testing, and release into a single workflow. Pgyer's official Fastlane plugin, fastlane-plugin-pgyer, uploads .ipa, .apk, and HarmonyOS .hap builds to Pgyer and returns the download page and QR code.

For help choosing between the API, CLI, CI/CD plugins, MCP, and Agent Skill, see Automated App Uploads and CI/CD Integration.

Prerequisites

macOS or Linux.
Ruby, Bundler, and Fastlane. See the Fastlane setup guide.
Your Pgyer API key, shown on the API information page.

Install the Plugin

In your project directory, run:

fastlane add_plugin pgyer

If the plugin is already installed, run fastlane update_plugins to get the latest version.

Store the API Key

Keep the API key in the PGYER_API_KEY environment variable (a secret in CI) rather than in your Fastfile:

export PGYER_API_KEY=your_api_key

You can also pass it as pgyer(api_key: "...").

Configure a Lane

In fastlane/Fastfile, add pgyer after the build action. The plugin uses the build that gym or gradle produced in the same lane, or the file you set with ipa, apk, or hap.

lane :beta do
  gradle(task: "assembleRelease")
  pgyer(update_description: "Fixed the login crash")
end

lane :beta do
  build_app(export_method: "ad-hoc")
  pgyer(update_description: "Fixed the login crash")
end

Build and sign the app with DevEco Studio or hvigorw assembleHap first, then upload the .hap file:

lane :beta_harmony do
  pgyer(
    hap: "entry/build/default/outputs/default/entry-default-signed.hap",
    update_description: "Fixed the login crash"
  )
end

Build and Upload

In your project directory, run:

fastlane beta

When the upload finishes, the output looks like this:

Build file: ./app/build/outputs/apk/release/app-release.apk (android)
Uploading app-release.apk (35.2 MB)...
Upload finished. Waiting for PGYER to process the build...
Published PGYER Demo 1.0.0 (build 1)
Download page: https://www.pgyer.com/pgyerdemo
QR code: https://www.pgyer.com/app/qrcodeHistory/...

Common Options

Option	Environment variable	Description
`api_key`	`PGYER_API_KEY`	Required. Your Pgyer API key
`apk`, `ipa`, `hap`	`PGYER_APK`, `PGYER_IPA`, `PGYER_HAP`	The build to upload; set at most one. Without one, the build from `gym` or `gradle` in the same lane is used
`update_description`	`PGYER_UPDATE_DESCRIPTION`	Release notes for this version
`description`	`PGYER_DESCRIPTION`	App description
`install_type`	`PGYER_INSTALL_TYPE`	`1` public, `2` password, `3` invitation only. If not set, the previous version's setting is kept; `password` alone selects password install
`password`	`PGYER_PASSWORD`	Install password
`install_start_date`, `install_end_date`	`PGYER_INSTALL_START_DATE`, `PGYER_INSTALL_END_DATE`	Install period, such as `2026-01-01`. Set both
`channel`	`PGYER_SPECIFIED_CHANNEL`	Short link of the channel to update
`user_download_file_name`	`PGYER_USER_DOWNLOAD_FILE_NAME`	File name testers download, in plain ASCII. Defaults to the name of the uploaded file
`oversea`	`PGYER_OVERSEA`	`true` for overseas upload acceleration, `false` for mainland China. If not set, Pgyer chooses by IP address
`processing_timeout`	`PGYER_PROCESSING_TIMEOUT`	Seconds to wait for Pgyer to process the build after the upload. Default `600`

Run fastlane action pgyer to see every option, or read the plugin documentation.

Use the Result

pgyer returns the build information from Pgyer, including appPgyerURL (the download page) and appQRCodeURL (the QR code image). The same values are stored in lane_context as PGYER_DOWNLOAD_URL and PGYER_QRCODE_URL, so later steps can use them, for example to send a notification:

lane :beta do
  build_app(export_method: "ad-hoc")
  result = pgyer(update_description: "Fixed the login crash")
  slack(message: "New beta: #{result['appPgyerURL']}")
end

Upgrading from Earlier Versions

Version 0.5.0 changes the following:

Without install_type, the previous version's install setting is kept. Earlier versions made the app public on every upload; set install_type: "1" if you want that.
When apk, ipa, or hap is set, that file is uploaded, and the app type comes from its extension.
Waiting for Pgyer to process the build stops after processing_timeout seconds instead of waiting forever.

Troubleshooting

Symptom	What to do
`Error loading plugin 'fastlane-plugin-pgyer'` or `Unable to activate faraday_middleware`	Plugin 0.3.x doesn't load on Fastlane 2.238.0 or later. Run `fastlane update_plugins`
API errors such as a wrong API key, missing real-name verification, or full storage	The log shows Pgyer's error code and how to fix it
`PGYER is still processing the build after 600 seconds`	The upload finished, so the build may still appear in your app list. For large builds, raise `processing_timeout`
`None of the PGYER API servers could be reached`	The plugin tries `www.pgyer.com`, `www.xcxwo.com`, and `www.pgyerapp.com` in turn. Check your network and proxy (`HTTPS_PROXY` is supported); if your DNS blocks these domains, set `doh: true`
The wrong build was uploaded	Set the file explicitly with `apk`, `ipa`, or `hap`

Upload via Fastlane

On this page