Repository navigation
Update Sources, Repository Linking & Signature Protection
This document explains how the five update sources work together in ApkUp, how you can link custom GitHub/GitLab projects, how ApkUp protects you against faulty updates and signature conflicts, and how to resolve any error message on your own.
- 🟢 Part 1: Explained Simply for Everyone (Plain Language)
-
💻 Part 2: Technical Documentation for Experts & Power Users
- 2.1 Parallel Multi-Source Aggregation & Version Verification
- 2.2 Cryptographic Signature Verification (SHA-1 & SHA-256) & Origin Detection
- 2.3 Direct APKMirror Resolution & Hardened
.apkmSplit Extraction - 2.4 Google Play Store / Aurora Dispenser Resilience & HTTP 429 Recovery
- 2.5 Three-Tier Repository Resolution for GitHub & GitLab
-
❓ Part 3: Comprehensive Frequently Asked Questions (FAQ) & Common Issues
- 3.1 Why does ApkUp sometimes show a warning icon for a "Signature Conflict"?
- 3.2 Do I have to sign in with my personal Google account to download Play Store updates?
- 3.3 Why does APKMirror sometimes still open my browser?
- 3.4 What are
.apkmfiles and can ApkUp install them directly? - 3.5 How do I prevent unfinished test versions (Alpha / Beta) from being offered?
- 3.6 Does ApkUp also support self-hosted GitLab servers?
- 3.7 Common Error: "Package conflicts with an existing package" (
INSTALL_FAILED_UPDATE_INCOMPATIBLE) - 3.8 Common Error: APKMirror shows an update, but the webpage says "404 Not Found"
- 3.9 Common Error: Google Play Store download fails (
HTTP 429or Paid Apps) - 3.10 Common Error: GitHub updates are temporarily not found (
HTTP 403 Rate Limit)
-
🛠️ Part 4: Common Error Messages & Self-Help (Troubleshooting)
- 4.1 DNS Error / Server Unreachable
- 4.2 Network Timeout / Connection Timed Out
- 4.3 Auth Error & Rate Limit (HTTP 401 / 403 / 429)
- 4.4 Server Error & Not Found (HTTP 404 / 500 / 502 / 503)
- 4.5 APKMirror Cloudflare Protection & Browser Fallback
- 4.6 Installation Failed & Signature Conflicts
- 4.7 Repository Linking & No Matching APK Asset
- 🔗 Part 5: Official Links & Further Resources
ApkUp combines seven open and mainstream distribution channels under a single unified interface. You can enable or disable each source individually in Setup:
| Source | What it is best for | Key highlight in ApkUp |
|---|---|---|
| Google Play Store | All regular everyday apps (messengers, browsers, tools). | Works completely anonymously without requiring a personal Google account. |
| APKMirror | Fast updates for major apps before the Play Store rolls them out to your device. | Automatically verifies architecture, Android version, and signature matching with per-app Cloudflare cooldowns. |
| IzzyOnDroid & F-Droid Repos | Free, open-source apps (FOSS) from IzzyOnDroid, Official F-Droid (f-droid.org), NewPipe, Guardian Project, microG, or custom HTTPS repos. |
Unified Setup bottom sheet with Index V2 entry.jar / index-v1.jar certificate verification, pre-pinned presets, and automatic TOFU pinning for custom repos. |
| GitHub | Popular open-source projects directly from the developer (e.g., NewPipe, Mihon, Seal, ApkUp itself). | Built-in catalog + custom repo bindings, optional regex asset filter, and token testing. |
| GitLab | Projects hosted on GitLab (e.g., Aurora Store, VLC, Briar, F-Droid). | Supports gitlab.com, self-hosted instances, and nested subgroups. |
| Codeberg / Forgejo | Community-driven FOSS apps (e.g., Gadgetbridge) hosted on Codeberg or Forgejo. | Supports codeberg.org, self-hosted Forgejo hosts, and optional access tokens. |
Previously, updating an app from APKMirror required opening a web browser and clicking through multiple ad-heavy download pages.
Since version 1.32, ApkUp handles this completely automatically for you:
- When you tap "Update" on an APKMirror update, ApkUp resolves the download link in the background, downloads the file, and installs it directly inside the app.
- You can find this toggle under Setup ➔ Update Sources ➔ Direct APKMirror Download.
Every Android app carries an invisible, tamper-proof cryptographic seal from its developer — the digital signature.
- Android only allows an update to be installed if the new version carries the exact same cryptographic seal as the version already installed on your phone.
- This prevents an attacker from installing a fake or modified version of an app (such as your banking app) over your genuine app.
- What ApkUp does for you: ApkUp compares signatures right during the update check! If a package on APKMirror or IzzyOnDroid does not carry the exact matching signature of your installed app, it is filtered out automatically so you never run into installation errors.
Many apps are available simultaneously on GitHub, IzzyOnDroid, and the Play Store.
- To keep your update list clean and clutter-free, ApkUp lists each app only once and automatically selects the best matching source for you.
- If you tap on an update card, the Update Details Sheet opens: under "Alternative Sources", you can see all other sources offering an update and switch between them with a single tap!
ApkUp already recognizes many popular open-source apps (like NewPipe, Seal, or Mihon) out of the box. If you have a specific app installed that publishes its updates on GitHub or GitLab, you can link it in seconds:
- Switch to the "Apps" tab in the bottom navigation bar.
- Find the desired app and tap on the link icon (or open its details).
- Select "Link Repository (GitHub / GitLab)".
- Paste the full link to the GitHub/GitLab page (e.g.,
https://github.com/TeamNewPipe/NewPipe) or the shorthand (TeamNewPipe/NewPipe) into the field and tap Save. - From now on, ApkUp will automatically check whether the developer has published a new release there during every update check!
-
Configurable Source Priority & Per-App Source Pinning (v1.44.0+):
- Global Source Priority: Open Setup ➔ Source Priority and reorder sources via long-press drag-and-drop or the up/down buttons to decide which source wins when multiple sources offer the same update.
- Per-App Source Pinning: Tap the pin action on an app in Apps or Updates to lock it to a preferred source (for example, always prefer GitHub over Play Store for a specific app). If the pinned source currently has no update, ApkUp automatically falls back to your global priority order.
ApkUp executes queries across all enabled sources concurrently and in isolation. As a result, a network outage or slow server on one source never blocks results from the remaining sources:
flowchart LR
Installed["Local Package Scanner\n(Installed Apps + Certificates)"] --> Orchestrator["Update Aggregator"]
Orchestrator --> Play["Google Play Store\n(Anonymous gplayapi)"]
Orchestrator --> AM["APKMirror\n(REST v2 Batch API)"]
Orchestrator --> Izzy["IzzyOnDroid\n(Repo Index + SHA-256)"]
Orchestrator --> GH["GitHub\n(REST API Releases)"]
Orchestrator --> GL["GitLab\n(API v4 Releases)"]
Play & AM & Izzy & GH & GL --> Dedupe["Deduplication, Signature\n& Version Verification"]
Dedupe --> UI["Updates Overview\n(Primary Card + Alternative Sources)"]
Two-Stage Version Verification: To eliminate false positives caused by inconsistent version naming across repositories, ApkUp verifies two criteria before surfacing an update:
- A strictly higher internal Android build number (
versionCode), whenever provided by the source index. - Semantic progression of the normalized version string (after stripping leading
v/Vprefixes and whitespace).
When scanning installed packages via the Android PackageManager (GET_SIGNING_CERTIFICATES on Android 9 / API 28+), ApkUp computes both the SHA-1 and SHA-256 fingerprints of each app's signing certificate:
- APKMirror: Strictly matches the SHA-1 fingerprint of the remote release against the local certificate of the installed app. If signatures do not match, the update is discarded automatically.
-
IzzyOnDroid: Matches the local certificate against the
signerhash (SHA-256) recorded in the repository index. -
Install Origin Detection:
Using
PackageManager.getInstallSourceInfo(), ApkUp determines the original installer of an app (e.g., Google Play Store, F-Droid, APKMirror, or Sideload). If an app originally installed via F-Droid or ReVanced receives an update from a source without pre-verifiable certificate metadata (such as GitHub Releases or the Play Store), ApkUp proactively displays a warning badge indicating a potential signature conflict.
Because APKMirror's public metadata endpoint only returns a link to the web variant page, ApkUp uses a three-stage link resolver with built-in safeguards for direct downloads:
-
Three-Stage Link Resolution:
-
Stage 1 (Variant Page): Extracts the download key and automatically detects whether the package is a standard standalone APK or a split bundle (
.apkm). - Stage 2 (Intermediate Download Page): Extracts the time-signed token URL.
- Stage 3 (CDN Redirect): Resolves the final binary package stream.
-
Stage 1 (Variant Page): Extracts the download key and automatically detects whether the package is a standard standalone APK or a split bundle (
-
Polite Rate-Limiting & Cloudflare Fallback:
- To respect APKMirror's servers, ApkUp enforces a minimum cooldown interval between consecutive resolutions.
- If Cloudflare's firewall requires an interactive security challenge (
HTTP 403,HTTP 429, or a Captcha challenge), ApkUp does not fail with an error; instead, it automatically hands off that specific app to the system browser.
-
Hardened
.apkmExtraction & Format Inspection:- Inspects every downloaded file based on its true ZIP structure (
AndroidManifest.xmlat the archive root = standalone monolithic APK; embedded.apkentries without a root manifest =.apkmsplit bundle). - Protects against Zip-Slip attacks (path traversal) by strictly rejecting archive entries containing relative path jumps (
..) or subdirectories. - Immediately purges any partially extracted split files if a download is interrupted or incomplete.
- Inspects every downloaded file based on its true ZIP structure (
For anonymous Google Play queries, ApkUp uses temporary guest sessions via the Aurora Dispenser infrastructure. Because these anonymous accounts are shared by users worldwide, Google may occasionally rate-limit individual sessions (HTTP 429 Too Many Requests):
-
Synchronized Session Rotation: When a download encounters an
HTTP 429rate limit, ApkUp discards the throttled guest token and requests a fresh guest session in a synchronized manner. Concurrent downloads automatically share the refreshed session without flooding the token dispenser. - Dispenser Cooldown: ApkUp enforces a strict cooldown interval between forced session renewals so the public dispenser infrastructure is never overloaded.
To map an Android package name (e.g., org.schabi.newpipe) to the right project on GitHub, GitLab, or Codeberg/Forgejo, ApkUp uses a three-tier priority cascade plus intelligent asset selection:
-
Priority 1 – Custom User Mapping: Projects manually linked by the user in the Apps tab via the 3-way repository bottom sheet (GitHub / GitLab / Codeberg; supports full URLs,
owner/reposhorthand, self-hosted instances, and an optional live-tested APK Asset Regex filter). - Priority 2 – Built-in Project Catalog: A curated mapping catalog bundled with ApkUp for well-known open-source apps.
-
Priority 3 – Automatic Source Discovery & FOSS Flavor Heuristic: While syncing F-Droid/IzzyOnDroid indexes, ApkUp automatically discovers upstream source URLs and prefers FOSS flavors for F-Droid-origin apps while deprioritizing
-debugor store-specific builds.
If you originally installed an app via F-Droid, that app was usually compiled and signed by F-Droid's build servers using F-Droid's own cryptographic key. When the developer publishes an update on GitHub or the Google Play Store, they sign it with their personal developer key.
- Android prohibits overwriting an app directly if the signing keys differ.
- That is why ApkUp warns you in advance! If you want to switch to the other source, you must uninstall the existing app once (which resets app data) and then perform a fresh install from the new source — or simply pick the matching source under "Alternative Sources".
No! ApkUp never asks for your Google account or password. For all queries and downloads from the Google Play Store, ApkUp uses temporary, completely anonymous guest sessions. Your privacy remains 100% protected.
APKMirror protects its website with Cloudflare against excessive automated traffic.
- If you download many apps from APKMirror in rapid succession, or if Cloudflare requests a human verification challenge (Captcha / "Verify you are human") for a specific app, ApkUp detects this immediately.
- Instead of failing with an error message, ApkUp automatically opens your web browser for that app so you can download the file seamlessly.
In the past, every Android app consisted of a single .apk file. Today, Google and APKMirror deliver many apps as split bundles (ending in .apkm on APKMirror) — an archive containing the base app alongside separate language, screen density, and CPU architecture split packages.
- Standard file managers cannot open
.apkmfiles directly. -
ApkUp supports
.apkmnatively: The app unpacks the archive automatically in the background and reassembles all split components seamlessly for Android!
Under Setup ➔ Filters & System, you will find two toggles:
- Ignore Alpha versions (enabled by default)
- Ignore Beta versions (enabled by default) This ensures you only receive stable production releases in everyday use. If you enjoy testing pre-release builds, you can turn these toggles off at any time.
Yes! When linking a repository in the Apps tab, you can paste not only links from gitlab.com, but also full URLs to independent or self-hosted GitLab instances (such as https://gitlab.gnome.org/... or enterprise GitLab servers). ApkUp automatically detects the custom hostname and queries its API v4 endpoint.
If the Android system aborts during installation and reports "App not installed as package conflicts with an existing package", one of two causes is always responsible:
-
Different Developer Signature: Your currently installed app comes from a different source (e.g., F-Droid or a patched ReVanced/modded build) than the downloaded update (e.g., GitHub or Google Play Store).
- Solution: Open the update card details in ApkUp and select the original source under "Alternative Sources" — or uninstall the old version once before installing the new one.
-
Version Downgrade: The downloaded file has a lower internal build number (
versionCode) than the currently installed version. ApkUp normally prevents this automatically during the update check.
This is a well-known behavior of APKMirror's backend infrastructure:
- When a new app version is uploaded to APKMirror, the backend often indexes it in the automated batch search API immediately, even before a moderator has approved the public download web page or while the CDN cache is still propagating.
-
How ApkUp handles this: ApkUp proactively checks target page availability in the background and filters out unapproved entries (
HTTP 404/503). If a page is still awaiting moderation at the exact moment you tap it, simply wait 15–30 minutes until APKMirror finishes publishing the page.
When downloading from the Google Play Store via the anonymous guest session, there are two common scenarios:
-
Server Rate Limit Reached (
HTTP 429 Too Many Requests): Because many users worldwide share the anonymous guest accounts, Google occasionally throttles a guest token briefly. Since ApkUp v1.32, the app detects this automatically, rotates to a fresh guest session in the background, and continues your download without interruption! - Paid Apps or Regional Restrictions: Because you use ApkUp anonymously (without your personal Google account), Google does not know which paid apps you have purchased. Paid apps must therefore be updated directly through the official Google Play Store app.
GitHub's public API allows a maximum of 60 unauthenticated requests per hour per IP address.
- If you have linked many GitHub apps and manually refresh several times within a few minutes (or share a public Wi-Fi / VPN IP address with many other users), this hourly GitHub limit can be reached.
- Solution: Under Setup ➔ Update Sources ➔ Configure GitHub Token, you can optionally add a free GitHub Personal Access Token (which raises the limit from 60 to 5,000 requests per hour), or simply wait briefly until GitHub resets your hourly quota automatically.
Whenever a red warning banner appears in the "Updates" tab (e.g., "Check failed (…) — Wiki Help ↗") or a download error occurs, you can find the exact cause below along with how to solve the problem yourself right away.
-
Displayed in ApkUp:
<Source> check failed (DNS error) -
What does this mean? Your phone could not resolve the server hostname of the update source (e.g.,
apkmirror.com,apt.izzysoft.de, orapi.github.com) into an IP address. -
How to fix it yourself:
- Check Ad Blockers / Private DNS: Are you using AdGuard, RethinkDNS, NextDNS, Blokada, or a custom Private DNS in your Android system settings? Some blocklists accidentally block APKMirror or GitHub domains. Temporarily pause the filter for 1 minute to test.
- Switch Wi-Fi / Mobile Data: Toggle Wi-Fi off and back on, or briefly switch to mobile data to flush your device's DNS cache.
-
Displayed in ApkUp:
<Source> check failed (Network timeout) - What does this mean? The source server did not respond quickly enough within the timeout window, or your data connection dropped during transmission.
- What does ApkUp do automatically? All other enabled update sources continue running independently and still display their discovered updates immediately.
-
How to fix it yourself:
- Check VPN: If you are using a VPN, switch to a different VPN server location or disconnect the VPN briefly.
- Check "Download on Wi-Fi only": If you are on mobile data, check under Setup ➔ Installation & Permissions whether the "Download on Wi-Fi only" toggle is enabled.
- Refresh again: Simply pull down on the updates list after 1–2 minutes (Pull-to-Refresh).
-
Displayed in ApkUp:
Auth error / HTTP 401,HTTP 403, orHTTP 429 - What does this mean? The source is temporarily throttling anonymous requests (Rate Limit) or a configured API token has expired.
-
How to fix it yourself (by source):
-
Google Play Store (
Auth error / HTTP 429): The public Aurora guest servers are temporarily busy. ApkUp automatically rotates to a fresh guest session on the next attempt — simply wait 1–2 minutes and refresh again. -
GitHub (
HTTP 403/HTTP 401): Without a token, GitHub only allows 60 requests per hour. Add a free Personal Access Token under Setup ➔ Update Sources ➔ Configure GitHub Token (instantly increases your limit to 5,000 requests/hour). If you seeHTTP 401, your saved token has expired or is invalid — clear or replace it there. -
GitLab (
HTTP 401/HTTP 403): Check under Setup ➔ Update Sources ➔ Configure GitLab Token whether your token is still valid and includes theread_apiscope.
-
Google Play Store (
-
Displayed in ApkUp:
HTTP 404,HTTP 500,HTTP 502, orHTTP 503 -
What does this mean?
-
HTTP 500 / 502 / 503: The update source server (e.g., GitHub, Google Play Dispenser, or IzzyOnDroid) is experiencing a temporary outage or maintenance. -
HTTP 404: A linked GitHub/GitLab repository was renamed or deleted, or a brand-new APKMirror release page is still awaiting moderator approval (see Section 3.8).
-
-
How to fix it yourself:
- For
HTTP 5xx, nothing is wrong on your phone — simply wait a few minutes until the server operator completes maintenance. - For
HTTP 404on GitHub/GitLab, open the "Apps" tab and tap the link icon on the affected app to verify whether the repository path (owner/repo) is still valid.
- For
- Displayed in ApkUp: "APKMirror blocked direct access (Cloudflare protection). Opening browser fallback…"
- What does this mean? APKMirror protects its servers using Cloudflare. Whenever Cloudflare demands a human verification challenge (Captcha) for your current IP address (common when using a VPN or after many rapid downloads), the app cannot bypass it silently in the background.
-
How to fix it yourself:
- Complete the in-app WebView or browser check: When Cloudflare requests verification during a download, ApkUp automatically opens an in-app WebView first (and falls back to your device browser if needed) — briefly complete the check and the download continues immediately.
- Avoid it long-term: Consider pausing your VPN during APKMirror downloads or updating apps in smaller batches rather than 20 apps at once.
- Displayed in ApkUp: "Installation failed for " or Android message "App not installed"
-
Most common causes & instant self-help:
- Resume a dismissed installation without re-downloading: If you accidentally dismissed the Android installer prompt, you do not need to download the file again! As long as the file is in the 24-hour cache, the button on the update card shows "Install" (instead of "Update") and launches the installer immediately without waiting.
-
Signature Conflict (
INSTALL_FAILED_UPDATE_INCOMPATIBLE): The installed app comes from a different source (e.g., F-Droid or ReVanced) than the update. Tap the update card and choose the original source under "Alternative Sources" (see Section 3.1). - Missing Permission "Install unknown apps": Open Setup ➔ Advanced Settings and check that "Install unknown apps" displays the green "Granted ✓" status.
-
Insufficient Storage (
INSTALL_FAILED_INSUFFICIENT_STORAGE): To unpack large apps (especially.apkmsplit bundles), Android temporarily requires roughly twice the file size in free storage space.
- Displayed in ApkUp: "No public GitHub release found", "No .apk asset attached to latest release", or "No APK asset matching device ABI"
-
What does this mean? The linked GitHub/GitLab project exists, but in the latest release the developer either uploaded only source code archives (
.zip/.tar.gz) or provided APK files exclusively for other CPU architectures (e.g.,x86_64for PCs instead ofarm64-v8afor smartphones). -
How to fix it yourself:
- In the "Apps" tab, tap the link icon next to the app and verify that the developer's official main repository is entered.
- If the developer no longer attaches pre-built
.apkfiles on GitHub, remove the custom repository link so ApkUp updates the app via IzzyOnDroid, APKMirror, or the Google Play Store instead.
Here you can find additional information and official documentation for all supported update sources and security mechanisms:
- 📦 APKMirror – Official FAQ & Security: apkmirror.com/faq (Background on signature verification and
.apkmsplit bundles) - 🛡️ IzzyOnDroid – Repository Documentation: apt.izzysoft.de/fdroid (Overview of the curated open-source repository)
- 🐙 GitHub – Releases Documentation: docs.github.com – About Releases (How developers publish APK assets on GitHub)
- 🦊 GitLab – Releases & API Documentation: docs.gitlab.com – Releases
- 🔐 Android Developers – App Signing: developer.android.com/studio/publish/app-signing (Official explanation from Google on why Android updates require matching cryptographic keys)