Getting started

Choose workflow based on whether you want GitHub to build for you or need local development and diagnostics.

Route	Installation on your computer	Best for
GitHub Template or fork	none	Users who want to edit morphe.toml, run Actions, and download verified artifacts.
Local CLI	Python, Java, and uv or pip	Development, debugging, custom automation, and offline verification.

Recommended: GitHub Template

Use repository as public template or fork, edit committed morphe.toml, then run Manual verified build from GitHub Actions. Hosted runner installs tools, downloads stock APKs, patches, signs, verifies, and uploads result.

No local uv, pipx, Python, Java, or Morphe Builder installation is required.

Complete walkthrough: Build with GitHub Template.

Local requirements

Tool	Version	Purpose
Python	3.11–3.13	Run Morphe Builder.
Java	21+	Run Morphe CLI, APKEditor, signer, and keytool.
uv	current	Install and run a source checkout.

Windows 10/11 and current Ubuntu Linux on x86-64 are supported. macOS and non-x86 builder hosts are not validated.

Confirm Java before downloading the toolchain:

java -version

Install locally

Install the published command globally:

uv tool install morphe-builder
morphe-builder --help

Or work from a source checkout:

git clone https://github.com/Villoh/morphe-builder
cd morphe-builder
uv sync --locked
uv run morphe-builder --help

Examples below use the installed command. Prefix them with uv run inside a source checkout.

Review configuration

morphe.toml declares apps, architectures, patches, providers, and tool versions. Validate patch selection and version resolution before a build:

morphe-builder list-patches morphe.toml

This command does not download APKs. It resolves the configured Morphe CLI and patch bundles from GitHub, then reports the effective app version and patch count.

See configuration reference before changing packages, patch options, provider URLs, or signer pins.

Choose Google Play access

Reliable Google Play access uses account-backed credentials:

GOOPDL_ACCOUNT_EMAIL
GOOPDL_AAS_TOKEN

Both values must be set together. Without them, Morphe Builder uses the anonymous dispenser and then configured fallback providers when Google Play is unavailable.

Generate and store credentials using the authentication guide. Never place them in morphe.toml, shell arguments, repository files, or caches.

Prepare tools

Download and hash the external Java tools:

morphe-builder tools

The command records exact release tags, asset URLs, sizes, and SHA-256 values in toolchain-provenance.json. Cached tools are reused only after validation.

Run a build

A build requires a keystore and its password. Keep private keystores outside the repository:

export MORPHE_KEYSTORE_PASSWORD='replace-me'
morphe-builder build morphe.toml \
  --keystore /path/outside/repository/builder.p12 \
  --output build

PowerShell equivalent:

$env:MORPHE_KEYSTORE_PASSWORD = 'replace-me'
morphe-builder build morphe.toml `
  --keystore C:\path\outside\repository\builder.p12 `
  --output build

The output directory must not already exist. Morphe Builder refuses to overwrite trusted artifacts.

A source checkout can use the public template keystore for local testing:

MORPHE_KEYSTORE_PASSWORD=morphe-builder uv run morphe-builder build morphe.toml \
  --keystore .github/template-release.p12 \
  --output build

The template key provides update compatibility only. It does not prove publisher identity; anyone can sign with it. See keystore policy.

Understand output

A successful build produces APKs, optional Magisk/KernelSU modules, provenance JSON files, and a build summary. Every published artifact links its stock input, toolchain, patches, signer, architecture, version, size, and SHA-256.

Static verification does not prove runtime behavior. Install and launch each APK on a matching test device before treating a release as stable.

Next reading:

1. Architecture for the complete pipeline.
2. APK build for patching and signing rules.
3. Troubleshooting when a command fails.