publish apt index (gh-pages-preview)

dists/stable/Release

@@ -0,0 +1,23 @@
+Architectures: arm64
+Codename: stable
+Components: main
+Date: Wed, 06 May 2026 07:10:23 +0000
+Label: CardputerZero
+Origin: CardputerZero
+Suite: stable
+MD5Sum:
+ 4e2aa46ed33d6756058bf8b05fb1a898              150 Release
+ 7f68f295bcc2c4f1991bb802ee31e32f              688 main/binary-arm64/Packages
+ ba6b8981a576ebf97880e2e188f16e8a              508 main/binary-arm64/Packages.gz
+SHA1:
+ a4d557e81d104df2b8dd1211969efde28ae32fcf              150 Release
+ 2082c8d1efc6ca14a4577ad683fae1225bb1c3d8              688 main/binary-arm64/Packages
+ ccb67757ca3cc30d42ca2f7dfb93dd49db849d41              508 main/binary-arm64/Packages.gz
+SHA256:
+ bd21c7b914649ee5e2bd71e113517f701e074a941128837f40685b99eb886c10              150 Release
+ cbda207ebf7a61f7f8cb9d8821b2d642f6c0dee3ac3dedb0f11f8a548c8806c1              688 main/binary-arm64/Packages
+ 26f4db77260017a2f82a6b2ea54055ebee773e695cbc3c58c9614320c199dfa3              508 main/binary-arm64/Packages.gz
+SHA512:
+ 0ee5e2859e93a8f6e968829c7be3069c17e9e90ad85c54242d04771b5d79aaac9677647669281f57142f39c249993e0f415ace66b8f1f86ba081aa01719ac224              150 Release
+ 00373c6151cf570529147e3ab8a75c68239c9957963cae624ef13618f36de1b90b1af8b73d94f03336bb242f3aa4d57f06d65bd023bc8cc4a0f0fdea2c1d9fd2              688 main/binary-arm64/Packages
+ c64016278c9229f742927411335d1c8d5effd53ad74ee73877280e92977d3b63984fa40886fba3281f594d2ea8e7feb29d49bb7ead93bf1ee79c9d9b12ba5f1f              508 main/binary-arm64/Packages.gz

dists/stable/main/binary-arm64/Packages

@@ -0,0 +1,14 @@
+Package: czrepo-hello
+Architecture: arm64
+Version: 0.1-1
+Maintainer: CardputerZero Repository <repo@m5stack.local>
+Filename: releases/download/apt-pool/czrepo-hello_0.1-1_arm64.deb
+Size: 784
+MD5sum: a4703c66a80bea45d9c45377ed6f235d
+SHA1: c3e62927584e90fb0265fd1282ac86058b45a640
+SHA256: dd80f7e4437219469afde60ecb79c80532d19e7ff1746270d322410415efcef3
+SHA512: f847524840b716e56363774663da65cd349235d08e6537cc1a02bacfa1c0d8bc542a2b8399a879bd63f6cd3f58154a025f9a7ccb9461d931d0a57fbb6b31bb9c
+Description: Bootstrap sentinel package used to validate publish.yml.
+ Ships a single file with a greeting; safe to dpkg -i on any arm64 host
+ because it only writes under /usr/share/czrepo-hello/.
+

index.md

@@ -0,0 +1,75 @@
+# CardputerZero Repository
+
+The official Debian `.deb` repository for [M5 CardputerZero](https://docs.m5stack.com/)
+applications — hosted on GitHub, served via GitHub Pages.
+
+## Quick start (on the device)
+
+```bash
+# Import the signing key
+curl -fsSL https://m5stack.github.io/CardputerZeroRepository/KEY.gpg \
+    | sudo tee /etc/apt/trusted.gpg.d/cardputer.asc > /dev/null
+
+# Add the repository
+echo 'deb [arch=arm64] https://m5stack.github.io/CardputerZeroRepository stable main' \
+    | sudo tee /etc/apt/sources.list.d/cardputer.list
+
+sudo apt update
+sudo apt install <appname>
+```
+
+## How it works
+
+- **Metadata** (`dists/stable/main/binary-arm64/Packages*`, `Release`, `InRelease`)
+  lives on the `main` branch and is republished to `gh-pages` on every push. This
+  is small text (~KB per app).
+- **`.deb` binaries** live as **GitHub Release assets**, not in the git tree. The
+  `Packages` index points to `https://github.com/m5stack/CardputerZeroRepository/releases/download/<tag>/<pkg>.deb`.
+  This avoids LFS quotas entirely.
+- **Signing** happens inside GitHub Actions using a GPG key stored as a repo secret.
+  The public key is committed as `KEY.gpg` so clients can verify `InRelease`.
+- **Submissions** come in as Pull Requests containing an uploaded `.deb` under
+  `incoming/`. The `validate-submission.yml` workflow runs on PR without
+  secrets (safe). On merge, `publish.yml` moves the file to a Release, rebuilds
+  the index, signs it, and pushes to `gh-pages`.
+
+## Architecture rationale
+
+Why GitHub Pages + Releases and **not** LFS? LFS on free plan is 1 GB storage /
+1 GB bandwidth per month — and **bandwidth counts even for public repos**. The
+Pages+Releases split avoids LFS entirely; see `docs/ARCHITECTURE.md` for the
+full writeup.
+
+## Submission flow
+
+Developers either:
+
+1. **`czdev upload <file.deb>`** from CardputerZero-AppBuilder — opens a PR in
+   this repo with the `.deb` dropped under `incoming/`.
+2. **Manual PR** — drop a `.deb` into `incoming/`, open a PR. CI validates
+   dpkg metadata + architecture + filename. Maintainer reviews, merges.
+
+Auth / signing for submitters is not wired yet — maintainer merge gates the
+publication.
+
+## Layout
+
+```
+CardputerZeroRepository/
+├── dists/stable/main/binary-arm64/   # apt metadata (Packages, Release, InRelease)
+├── pool/main/                        # reserved; small debs may land here later
+├── incoming/                         # PR landing zone, emptied on merge
+├── KEY.gpg                           # public signing key
+└── .github/workflows/
+    ├── validate-submission.yml       # PR safety: verify deb format only
+    └── publish.yml                   # on merge to main: release + reindex + sign
+```
+
+## Status
+
+- [x] Repo structure bootstrapped (this PR)
+- [x] `validate-submission.yml` — checks deb header, architecture=arm64
+- [x] `publish.yml` — builds Packages/Release, signs, pushes to gh-pages
+- [ ] GPG signing key added as secret (see `docs/MAINTAINERS.md`)
+- [ ] GitHub Pages enabled on `gh-pages` branch
+- [ ] `czdev upload` subcommand wired to this flow (CardputerZero-AppBuilder)