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, and MCP accept PGYER_API_KEY; use each plugin's 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

The Jenkins plugin lets you configure the API Key, package directory, and file matching rules in a job's post-build actions. Use its returned variables in subsequent steps.

For Jenkins Pipeline, you can also run the CLI or Shell commands above after building and inject the API Key through Jenkins credentials.

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.

GitHub Actions

Use the Pgyer upload Action, checking the selected version's action.yml for inputs and runtime compatibility, or invoke the CLI in your existing workflow.

Place this snippet after the build steps in the same job. It assumes a suitable Node.js environment is available and PGYER_API_KEY is stored in repository Secrets:

- 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 build retention and automatic cleanup rules. Keep packages 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.
• Travis CI for Android and Travis CI for iOS: Existing integration tutorials; adapt historical example environments to current platform settings.
• Third-party plugins: Integrations for Gradle, TeamCity, and other tools. 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.