You've already forked CardputerZeroRepository
mirror of
https://github.com/m5stack/CardputerZeroRepository.git
synced 2026-05-20 11:52:05 -07:00
LiHaohua
774d9a86fa
This is the initial shape of the CardputerZero deb repository. The design follows the GitHub Pages (metadata) + Releases (deb assets) pattern that sibling projects like ryanfortner/box64-debs and AdityaGarg8/t2-ubuntu-repo use successfully — it deliberately avoids Git LFS because the free plan's 1 GB/1 GB storage+bandwidth limits apply to public repos too. Files landing here: - README.md / docs/ARCHITECTURE.md / docs/MAINTAINERS.md explain the flow for users, the design tradeoffs, and the maintainer runbook (including GPG key setup). - .github/workflows/validate-submission.yml runs on pull_request with a read-only token and no secrets, verifying any incoming/*.deb is a valid arm64 package. Safe to run on external contributor PRs. - .github/workflows/publish.yml runs on push to main (after merge). It uploads incoming/*.deb to a rolling "apt-pool" GitHub Release, rebuilds Packages/Release/InRelease with apt-ftparchive, GPG-signs if GPG_PRIVATE_KEY is set (warns loudly otherwise), and publishes the metadata tree to gh-pages. - incoming/czrepo-hello_0.1-1_arm64.deb is a 784-byte sentinel package used to exercise the publish pipeline end-to-end on this very first PR merge. The workflow is intentionally safe-by-default: without a GPG key configured it will still produce a usable (unsigned) apt index so the plumbing can be validated before trusted signing keys are generated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
76 lines
3.1 KiB
Markdown
76 lines
3.1 KiB
Markdown
# 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)
|