mirror of https://github.com/m5stack/CardputerZeroRepository.git synced 2026-05-20 11:52:05 -07:00

Files

T

LiHaohua 774d9a86fa Bootstrap apt repository structure

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>

2026-05-06 14:56:07 +08:00

3.1 KiB

Raw Permalink Blame History

CardputerZero Repository

The official Debian .deb repository for M5 CardputerZero applications — hosted on GitHub, served via GitHub Pages.

Quick start (on the device)

# 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:

czdev upload <file.deb> from CardputerZero-AppBuilder — opens a PR in this repo with the .deb dropped under incoming/.
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

Repo structure bootstrapped (this PR)
validate-submission.yml — checks deb header, architecture=arm64
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)

3.1 KiB Raw Permalink Blame History