fdroid-repo-ci/README.md

# fdroid-repo-ci

Shared tooling to sign a prebuilt APK, build a signed F-Droid repo index over
it, and publish the result to an S3-compatible bucket -- consumed as a
composite action by whichever repository currently holds the signing keys
and runs the publish. Which repository that is has changed more than once,
so nothing here names it; see "Not hard-coded" below.

Same shape as [weblib-ci], and public for the same measured reason: a
private repository cannot be consumed cross-repo via `uses:` on this Gitea
instance (see weblib-ci's README) -- every cross-repo form fails while the
repo being referenced is private, and only the full-URL form works once it
is public.

**Nothing secret belongs here, ever.** Keys, keystores, credentials, bucket
names and hostnames all live in the private repo that consumes this one and
arrive as inputs -- arguments and environment variables, never committed
here.

## What is here

| script | what it does |
|---|---|
| `sign-apk.sh` | check alignment, then sign a prebuilt unsigned release APK with a keystore the caller supplies |
| `fdroid-update.sh` | run `fdroid update` over a `repo/` directory of already-signed APKs and produce the signed index |
| `publish.sh` | upload the resulting repo tree to an S3-compatible bucket |
| `with-nixpkgs.sh` | run a command with one or more nixpkgs packages on PATH, pinned to the revision in `nixpkgs-pin` |
| `check_zip_alignment.py` | the alignment check `sign-apk.sh` runs before signing (see "Align before sign" below) |
| `action.yml` | the composite action a consumer includes to get all of the above |

Deliberately **not** in scope: fetching the APK. That needs an upstream
credential and is the consumer's business, not the tooling's -- which also
keeps this repo from knowing which upstreams exist.

All of it is standard library / plain bash plus the pinned tools below. They
are *run*, not built, so this repo has no flake -- see "Pinning nixpkgs"
below for what that costs and why it is still the right call here.

## Using it

```yaml
- uses: actions/checkout@v4
- id: ci
  uses: https://git.chaosbit.de/weblib/fdroid-repo-ci@main
- env:
    APK_KEYSTORE_PASSWORD: ${{ secrets.APK_KEYSTORE_PASSWORD }}
  run: |
    bash "${{ steps.ci.outputs.path }}/sign-apk.sh" \
      app-release-unsigned.apk app-release.apk \
      "$APK_KEYSTORE" release-key APK_KEYSTORE_PASSWORD

- env:
    INDEX_KEYSTORE_PASSWORD: ${{ secrets.INDEX_KEYSTORE_PASSWORD }}
  run: |
    bash "${{ steps.ci.outputs.path }}/fdroid-update.sh" \
      "$FDROID_REPO_ROOT" "$INDEX_KEYSTORE" repo-key INDEX_KEYSTORE_PASSWORD

- env:
    AWS_ACCESS_KEY_ID: ${{ secrets.PUBLISH_ACCESS_KEY_ID }}
    AWS_SECRET_ACCESS_KEY: ${{ secrets.PUBLISH_SECRET_ACCESS_KEY }}
  run: |
    bash "${{ steps.ci.outputs.path }}/publish.sh" \
      "$FDROID_REPO_ROOT/repo" "$BUCKET" "$S3_ENDPOINT_URL"
```

**Use the full URL, `https://git.chaosbit.de/weblib/fdroid-repo-ci@main`, not
`weblib/fdroid-repo-ci@main`.** Measured on weblib-ci (weblib-archive#44):
the bare `owner/repo` form resolves against the instance's default actions
URL rather than this host and fails outright. The full-URL form is also the
only one that works while a referenced repo is private -- irrelevant for
*this* repo, which is public on purpose, but relevant for whatever repo is
consuming it, since that one holds the keys.

`$APK_KEYSTORE`/`$INDEX_KEYSTORE`/`$FDROID_REPO_ROOT`/`$BUCKET`/
`$S3_ENDPOINT_URL` above are the consumer's own paths and values -- nothing
in this repo defaults or hints at them. Env var *names* like
`APK_KEYSTORE_PASSWORD` are the consumer's choice too, not a convention this
repo imposes: `sign-apk.sh` and `fdroid-update.sh` each take the name of the
environment variable to read a password from as an argument, specifically so
two different keystores in the same job (the APK key and the separate repo
index key -- see below) never have to share one variable name.

## Align before sign, and how "no `zipalign`" was verified

`zipalign` then `apksigner`. Signing first and aligning after is the old
`jarsigner`-era order and invalidates an `apksigner`-era (v2/v3) signature,
because that scheme signs the exact bytes of the packaged zip and alignment
padding changes those bytes.

**`apksigner` is a standalone nixpkgs attribute** (`nixpkgs#apksigner`,
verified at 35.0.6). **`zipalign` is not** -- it exists only inside
`androidenv`'s composed build-tools, which pulls a full versioned Android SDK
and its licence machinery for one binary. Before accepting that as a
dependency, three things were measured rather than assumed:

1. **Google's own docs** (developer.android.com/tools/zipalign): "If you
   build using Android Studio, which uses the Android Gradle plugin (AGP),
   this is done automatically. In this case, you should still use zipalign
   to verify that the APK is aligned, but you don't need to align it." AGP is
   what `flutter build apk` (or any Gradle-based Android build) drives
   underneath, so this applies to any such build's output, not just
   Android-Studio-initiated ones.
2. **`fdroidserver` 2.4.3's own source never calls `zipalign`, anywhere** --
   grepped across all 38 of its modules. Its APK-signature-copying code
   (`apksigcopier.py`, used for reproducible-build verification, a different
   flow than binary-repo mode) implements realignment itself in pure Python
   against the zip format directly, rather than shelling out to the
   `zipalign` binary.
3. **`apksigner` does not check or enforce alignment at all**, in either
   direction -- measured directly: a deliberately misaligned fixture zip
   (including a `.so` misaligned to the stricter 4096-byte boundary) was
   signed and then verified with `apksigner verify --verbose`, and the
   output carried no warning about alignment whatsoever.

**Confidence: high** that a Gradle/AGP-built unsigned release APK is already
aligned, resting on (1) and (2) above. **Not independently confirmed**
against a real `flutter build apk` output run in this environment -- that
build was judged too expensive to attempt for this measurement. A sibling
repo's own CI proposal for building the Flutter app was rejected on the same
"the toolchain is too large to pull on every push" grounds this pin sidesteps
(composing a multi-platform Android SDK plus NDK pulls tens of gigabytes),
and the host available for this measurement had well under that in free
disk space.

Point (3) is why this repo does not simply trust point (1) and move on:
since nothing downstream complains about misalignment either, a build that
stopped emitting aligned output would fail silently -- an APK that signs and
verifies fine but behaves badly (or refuses to install) on a real device.
`check_zip_alignment.py`, a few lines against the standard library `zipfile`
module, checks every uncompressed entry of the APK `sign-apk.sh` is asked to
sign, and refuses to sign one that fails it. If that check ever legitimately
trips, the fix is to add `androidenv`'s `zipalign` as a dependency here, not
to weaken or remove the check.

## The repo index key is not the APK signing key

Binary-repo mode (every APK arrives already signed) means `fdroid update`
reads each APK's existing signature and never touches an app's own signing
key. It signs the **index** with a separate key of its own -- `fdroid-update.sh`
takes its own keystore/alias/password arguments, deliberately unrelated to
`sign-apk.sh`'s. Conflating the two would mean one compromised key
undermines both the apps and the index that vouches for them.

`fdroid-update.sh` writes `<repo-root>/config.yml` itself, on every run,
using fdroidserver's own `{env: VARNAME}` indirection for both passwords --
the exact mechanism its `common.py` implements *specifically so config.yml
can be safely git-managed*: "it is a good idea to manage config.yml (WITHOUT
PASSWORDS!) in git." A caller never has to know or hand-write fdroidserver's
config format.

## Pinning nixpkgs

`fdroidserver`'s output feeds a *signed index*, so an unpinned or
channel-drifting nixpkgs is a worse trade here than for a disposable test
job. This repo carries a `nixpkgs-pin` file -- one line, a 40-character
nixpkgs revision -- and `with-nixpkgs.sh` refuses to run at all if that file
is missing or malformed, rather than silently falling back to an unpinned
`nix shell nixpkgs#foo`, which re-resolves the registry and fetches whatever
the channel currently points at.

This is deliberately **not** the same mechanism as [weblib-ci]'s
`with-nixpkgs.sh`, which reads the *consuming* repo's `flake.lock`. This repo
has no flake (see weblib-ci#9 for the same tension in that repo: a
`flake.lock` existing only to hold one revision string), and per this repo's
own originating issue, the repo that consumes it holds signing keys and is
not guaranteed to be a flake either -- reading a caller's `flake.lock` the
way weblib-ci's script does would not even find one here. So the pin travels
with *this* repo instead, in a file named `nixpkgs-pin` on purpose: it is the
exact fallback weblib-ci#9 proposes adding to the shared script (flake.lock
present -> today's behaviour there; else `nixpkgs-pin` -> a bare revision;
else fail loudly). If that lands, this repo already speaks its format and
nothing here needs to change.

A `nixpkgs-pin` file has no `nix flake update` -- it is bumped by hand.
Accepted here for the same reason weblib-ci#9 accepted it for a
stdlib-only test suite, generalised: the alternative (a flake that builds
nothing, just to hold a lockfile) is a lot of structure for one string, and a
genuinely broken pinned nixpkgs would be caught immediately by this repo's
own test suite.

`fdroidserver` is in nixpkgs as `fdroidserver`, verified at 2.4.3.
`publish.sh` uses `awscli2` for the same S3-compatible upload every consumer
here needs, resolved through the same pin.

## Testing

```bash
bash run_tests.sh
```

42 assertions across five suites, ~20s on a warm nix store:

* `test_check_zip_alignment.py` -- pure standard library, no nix, no
  network at all; builds an aligned and a misaligned fixture zip by hand and
  checks both directions, including the 4096-byte boundary specific to `.so`
  entries.
* `test_with_nixpkgs.sh` -- offline; every way the pinning wrapper is
  supposed to refuse rather than silently degrade (missing pin, malformed
  pin, too few arguments). Does not exercise the happy path of actually
  resolving a `github:nixos/nixpkgs/...` reference automatically, since that
  needs network (or an already-warm local cache) the same way weblib-ci's
  own `with-nixpkgs.sh` does, and that repo does not automate a test for it
  either. It was checked by hand instead.
* `test_sign_apk.sh` and `test_fdroid_update.sh` -- full end-to-end runs
  against a throwaway keystore generated fresh per run, real `apksigner`
  and `fdroid update`. Needs the pinned toolchain to be resolvable (locally
  cached, or fetched once over the network); nothing beyond that.
* `test_publish.sh` -- argument/credential validation and `--dry-run`
  command construction, fully offline, plus one real invocation against a
  closed local port (`127.0.0.1:1`, nothing listens there) to prove the
  built command genuinely attempts a network call rather than failing on its
  own arguments. The actual upload path is out of scope for an offline
  suite, matching the constraint that only `publish.sh` needs network in the
  first place.

No `.gitea/workflows` runs this, on the same reasoning weblib-ci#9 recorded:
run it by hand before pushing. If that changes for weblib-ci it should
probably change here too, at the same time.

## Not hard-coded

No `weblib/` (or any other organisation) in a path, URL or workflow
reference. No bucket name, repo URL, app id, keystore path, or channel name
or count -- a consumer may have one publish target or several, under
whatever names it likes; nothing here assumes "release" and "dev", or that
there are exactly two.

[weblib-ci]: https://git.chaosbit.de/weblib/weblib-ci