Automated App Uploads and CI/CD Integration

Upload a package to Pgyer after your build completes, obtain its download link and QR code, and share them with testers. This guide helps you choose an integration and get started. Follow the linked guides for complete parameters and platform-specific configuration.

The Complete Upload Workflow

Build and sign the package → Upload to Pgyer → Wait for release processing → Obtain a download link or QR code → Share with testers.

Your development tools or CI/CD system build and sign the package. Pgyer receives it, processes the release, and provides download distribution. Make sure a usable package exists before running the upload step.

Choose an Integration

Start with the CLI if you have not chosen a tool. Choose the fast upload API for deeper integration into your own system. The language examples implement this API; the Shell example is one of those implementations.

Before You Start

1. Prepare a built and signed package. The fast upload API and CLI accept .ipa, .apk, and .hap; check each plugin's documentation for supported formats. See HarmonyOS beta distribution for certificate and dependency requirements.
2. Sign in to Pgyer and obtain your API Key from API Info.
3. Store the key in your CI/CD secret or credential manager and inject it into the upload step. The CLI, Shell example, MCP, Fastlane plugin, and Gradle plugin accept PGYER_API_KEY; for other plugins, use their documented authentication parameters.
4. Ensure the upload step can read the package and reach the Pgyer API and the returned upload endpoint. Transfer or download build artifacts when building and uploading in separate jobs.

Keep real API keys out of Git and build logs. Automated uploads use credentials supplied by the pipeline and do not require interactive login on each run.

Quick Start with the CLI

Install the CLI on a machine that meets its runtime requirements:

npm install -g @pgyer/cli

Configure PGYER_API_KEY in your CI/CD system, then run:

pgyer upload ./app-release.apk

Replace the path with your package path and quote paths containing spaces. The CLI waits for Pgyer processing to finish by default; add --json for machine-readable results. For local development, you can run pgyer auth login before uploading.

For example, add these Shell commands after your existing build step:

set -eu
: "${PGYER_API_KEY:?Configure PGYER_API_KEY in your CI/CD system first}"
test -f ./app-release.apk
pgyer upload ./app-release.apk

This snippet assumes the CLI is installed and the package is in the current working directory. Pin a tested CLI version in your production pipeline. Run pgyer upload --help or see the CLI guide for more options.

For an existing Shell environment, download the Shell example into your script directory. Follow its dependency instructions, configure PGYER_API_KEY, and run:

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

Integrate Your System with the Fast Upload API

Use the fast upload API for new integrations. It has three steps:

1. Get upload credentials: Call getCOSToken to obtain the upload endpoint, file key, and signed parameters.
2. Upload the package: Send the file and signed parameters to that endpoint using multipart/form-data, as described in the API reference. Use the address and parameters from the response.
3. Check the release result: Pass the first step's key as the buildKey query parameter to buildInfo. Wait for processing to finish and retrieve the app information.

The example repository contains runnable implementations:

Each directory documents dependencies, arguments, and error handling. See the upload API reference for complete request and response fields.

Connect Your CI/CD Tools

Jenkins

With the Jenkins plugin, call pgyerUpload in a Pipeline, or add the "Upload to PGYER" build step to a Freestyle job. The plugin uploads from the node running the build, keeps the API Key in Jenkins credentials, and returns the download page and QR code for later steps.

Fastlane

Install the plugin in your project:

fastlane add_plugin pgyer

In a lane with packaging already configured, add this immediately after the packaging step:

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

See the Fastlane guide and plugin repository for package paths, release notes, and installation settings.

Gradle

Add the Gradle plugin to your Android app module:

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

With PGYER_API_KEY set in your CI/CD, run:

./gradlew uploadPgyerRelease

The plugin builds the variant's APK first, then uploads it, and writes the download page to build/outputs/pgyer/release.json in the app module. PgyerUploadTask also uploads ipa and hap files. See the Gradle plugin guide.

GitHub Actions

Add the Pgyer upload Action after the build steps and store PGYER_API_KEY in repository Secrets:

- 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 }}

The Action uploads apk, ipa, and hap builds, and the step fails if the upload fails. Later steps can use steps.pgyer.outputs.appPgyerURL (the download page) and steps.pgyer.outputs.buildQRCodeURL (the QR code). See the Action documentation for every input and output. Workflows still on v1.3 should switch to @v2.

You can also run the CLI in an existing workflow. Place this snippet after the build steps in the same job. It assumes a suitable Node.js environment is available:

- 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

Replace the package path and choose a release trigger that can access the secret. Pin the CLI version after testing it in your environment.

GitLab CI and Other Platforms

In a job or step after the build, install the CLI, inject PGYER_API_KEY, and run the upload command. GitLab CI can store the key in CI/CD Variables and transfer the package to the upload job using artifacts.

The same workflow applies to other systems: prepare the runtime, obtain the artifact, configure authentication, upload, and check the result. Platforms that execute scripts or send HTTP requests can integrate this way.

Upload with AI: MCP and Agent Skill

MCP: Give AI Upload and Query Tools

Pgyer MCP exposes tools for uploading packages, listing apps, and querying app information by short link to compatible AI clients.

Configure your client using the MCP guide and ensure the tool's runtime can read the package. Then ask your assistant:

Agent Skill: Guide AI Through the Workflow

Pgyer Agent Skill supplies upload selection guidance, result formatting, CI/CD examples, and troubleshooting instructions. Install it with the following command, then configure authentication as described in its guide:

npx skills add PGYER/pgyer-skill

Ask AI to upload an existing package or help configure your pipeline:

MCP supplies callable tools, while the Skill guides how AI selects and combines operations. They can work together. The current Skill prefers available MCP tools and also provides Shell and API paths; see the Skill repository for details.

Review generated pipeline configuration against your project's build commands, artifact paths, and triggers, then run it to verify the integration. Subsequent automated uploads are executed by the pipeline.

Upload Results and Common Release Settings

After a successful fast API release, these fields are available in buildInfo's data. CLI and plugin output formats are documented by their respective tools.

Add the download link to your build summary or pass it to your existing notification step to share with testers. See the Webhook guide for notification integration.

Common settings include release notes, public or password-protected installation, invited installation, and targeting an existing channel. The fast API parameters are buildUpdateDescription, buildInstallType, buildPassword, and buildChannelShortcut. Tool parameter names may differ; consult the corresponding guide.

Common Questions

Can I Integrate Without a Dedicated Plugin?

Yes. Systems that execute commands or call HTTP APIs can use the CLI, Shell, or fast upload API. The upload step needs access to the package and relevant services.

How Should I Handle Failures or Timeouts?

Check the package path, file permissions, API Key, and network, then read the returned error. Continue polling only for documented processing states; stop and address explicit failures. After a timeout, verify the release result before deciding to upload again to avoid duplicate submissions.

Will Uploaded Packages Be Kept Indefinitely?

Automated uploads follow the same account storage and historical-build cleanup rules. When storage is exceeded, the main account's policy applies, and insufficient space may cause an API failure. Check the final publishing status and keep installers needed for long-term use in your CI/CD artifact store or archive system.

More Development Tools

• Android Studio plugin: Select and upload APKs manually inside the IDE.
• Third-party plugins: Community-maintained tools such as a Flutter release tool and a Gradle plugin. Check each project's maintenance status and compatibility before use.

The individual guides continue to provide complete installation steps, parameters, and examples. Use the selection table to find the relevant guide.