From a3a7c2228fc6285789f68a5c552a5033a44ea595 Mon Sep 17 00:00:00 2001 From: Tarik Moussa Date: Thu, 4 Jun 2026 10:48:33 +0200 Subject: [PATCH] ci: add Codeberg CI (Woodpecker + Forgejo) and document CI/CD topology Add a lightweight test-fast pipeline for the public Codeberg mirror so it shows a build status, defined for both CI systems Codeberg offers: - .woodpecker.yml (Woodpecker, debian:bookworm) - .forgejo/workflows/ (Forgejo Actions, node:20-bookworm, runner label docker) Both run the pure-math suite only (Eigen vendored, GTest via FetchContent; no CGAL/Boost), using public images and the docker runner label since the private eulernest ci-cpp image and Pi runner are unreachable from Codeberg. Docs: - new doc/architecture/ci-cd.md: two-forge topology, runners, trigger keywords, mirror mechanism. - fix stale "codeberg/main ... no CI" claim in contributing.md and bring the CI table up to date. - link the new doc from the README doc index. Co-Authored-By: Claude Opus 4.8 --- .forgejo/workflows/cpp-tests.yml | 65 ++++++++++++++++++ .woodpecker.yml | 31 +++++++++ README.md | 1 + doc/architecture/ci-cd.md | 110 +++++++++++++++++++++++++++++++ doc/contributing.md | 30 ++++++--- 5 files changed, 229 insertions(+), 8 deletions(-) create mode 100644 .forgejo/workflows/cpp-tests.yml create mode 100644 .woodpecker.yml create mode 100644 doc/architecture/ci-cd.md diff --git a/.forgejo/workflows/cpp-tests.yml b/.forgejo/workflows/cpp-tests.yml new file mode 100644 index 0000000..9b6f2cd --- /dev/null +++ b/.forgejo/workflows/cpp-tests.yml @@ -0,0 +1,65 @@ +# Forgejo Actions — Codeberg (https://codeberg.org) +# +# Codeberg counterpart of the eulernest Gitea pipeline +# (.gitea/workflows/cpp-tests.yml). Two differences are required because +# Codeberg's shared runners are not the Pi runner: +# +# * runs-on: docker — Codeberg shared-runner label (not "eulernest") +# * image: node:20-bookworm — public image (the private git.eulernest.eu +# ci-cpp image is unreachable from Codeberg). +# node:20 ships the Node runtime that +# actions/checkout@v4 needs; build tools are +# apt-installed in the first step. +# +# Scope: "test-fast" only — the pure-math suite (Eigen vendored, GoogleTest via +# FetchContent, no CGAL/Boost). A red job here = a red Codeberg CI badge. + +name: C++ Tests (Codeberg) + +on: + push: + branches: + - main + - "claude/**" + - "feature/**" + - "review/**" + pull_request: + +jobs: + test-fast: + runs-on: docker + container: + image: node:20-bookworm + + steps: + - uses: actions/checkout@v4 + + - name: Install build deps (cmake, g++, make) + run: | + apt-get update -qq + apt-get install -y --no-install-recommends \ + cmake g++ make git ca-certificates + + - name: Configure (tests-only — Eigen + GoogleTest) + run: cmake -S code -B build -DCMAKE_BUILD_TYPE=Release + + - name: Build + run: cmake --build build --target conformallab_tests -j$(nproc) + + - name: Run tests + run: > + ctest --test-dir build + --output-on-failure + --output-junit test-results.xml + + - name: Summary + if: always() + run: | + if [ -f build/test-results.xml ]; then f=build/test-results.xml; else f=test-results.xml; fi + if [ -f "$f" ]; then + total=$(grep -o 'tests="[0-9]*"' "$f" | grep -o '[0-9]*' | head -1) + failed=$(grep -o 'failures="[0-9]*"' "$f" | grep -o '[0-9]*' | head -1) + skipped=$(grep -o 'skipped="[0-9]*"' "$f" | grep -o '[0-9]*' | head -1) + passed=$(( ${total:-0} - ${failed:-0} - ${skipped:-0} )) + echo "FAST ▸ TOTAL ${total:-0} | PASSED $passed | FAILED ${failed:-0} | SKIPPED ${skipped:-0}" + fi diff --git a/.woodpecker.yml b/.woodpecker.yml new file mode 100644 index 0000000..72cc685 --- /dev/null +++ b/.woodpecker.yml @@ -0,0 +1,31 @@ +# Woodpecker CI — Codeberg (https://ci.codeberg.org) +# +# Runs on every push / PR. Mirrors the "test-fast" job of the +# eulernest Gitea pipeline (.gitea/workflows/cpp-tests.yml), but uses a +# plain public Debian image instead of the private ci-cpp registry image, +# because Codeberg's shared runners cannot pull git.eulernest.eu. +# +# Pure-math test suite only (Clausen, ImLi2, hyper-ideal geometry): +# * Eigen is vendored → code/deps/eigen-3.4.0 +# * GoogleTest via FetchContent (network at configure time) +# * No CGAL / Boost / Wayland needed → fast, headless, < 2 min +# +# A failing build or any failing ctest makes the Codeberg CI badge red. + +when: + - event: [push, pull_request] + +steps: + test-fast: + image: debian:bookworm + commands: + - apt-get update -qq + - >- + apt-get install -y --no-install-recommends + cmake g++ make git ca-certificates + - cmake -S code -B build -DCMAKE_BUILD_TYPE=Release + - cmake --build build --target conformallab_tests -j$(nproc) + - >- + ctest --test-dir build + --output-on-failure + --output-junit test-results.xml diff --git a/README.md b/README.md index 7161007..43f4dba 100644 --- a/README.md +++ b/README.md @@ -142,6 +142,7 @@ Layout2D layout = euclidean_layout(mesh, res.x, maps); | **geometry-central comparison** — shared core, demarcation, adoption candidates, scientific added value | [doc/architecture/geometry-central-comparison.md](doc/architecture/geometry-central-comparison.md) | | **Design decisions** — key architectural choices + rationale | [doc/architecture/design-decisions.md](doc/architecture/design-decisions.md) | | **Project structure** — directory tree + build targets | [doc/architecture/project-structure.md](doc/architecture/project-structure.md) | +| **CI / CD** — two-forge topology, runners, trigger keywords, mirror | [doc/architecture/ci-cd.md](doc/architecture/ci-cd.md) | | **Discrete conformal theory** — mathematical background for collaborators | [doc/math/discrete-conformal-theory.md](doc/math/discrete-conformal-theory.md) | | **Validation** — known analytic results + how to verify them | [doc/math/validation.md](doc/math/validation.md) | | **Validation protocol** — concrete commands with expected outputs | [doc/math/validation-protocol.md](doc/math/validation-protocol.md) | diff --git a/doc/architecture/ci-cd.md b/doc/architecture/ci-cd.md new file mode 100644 index 0000000..3a9b94b --- /dev/null +++ b/doc/architecture/ci-cd.md @@ -0,0 +1,110 @@ +# CI / CD + +Single source of truth for **how continuous integration is wired** across the +two forges this project lives on. If you add, move or rename a workflow, update +this page. + +## TL;DR + +| Forge | Remote | Role | CI system | Config | Runner | +|---|---|---|---|---|---| +| **eulernest Gitea** | `origin` | Authoritative gate (full test + quality suite) | Gitea Actions | `.gitea/workflows/` | self-hosted Raspberry Pi (ARM64), label `eulernest` | +| **Codeberg** | `codeberg` | Public mirror + public build badge | Woodpecker **and** Forgejo Actions | `.woodpecker.yml`, `.forgejo/workflows/` | Codeberg shared runners, label `docker` | + +The two forges are connected by a one-way mirror: every push to `main` on +eulernest is force-mirrored to Codeberg (see +[Mirror](#mirror-eulernest--codeberg) below). Codeberg never pushes back. + +Why two CI systems on Codeberg? They are independent and either may be enabled +per-repo; providing both means the public build status is green regardless of +which one the repo has switched on. They run the **same** `test-fast` build. + +--- + +## eulernest Gitea (`origin`) — the real gate + +Self-hosted Gitea with a single self-hosted runner: a Raspberry Pi (ARM64, +3–4 GB RAM). Because the runner is RAM-constrained, the heavy jobs are +**keyword-gated** (opt-in per commit) rather than run on every push. + +All C++ jobs use the private image `git.eulernest.eu/conformallab/ci-cpp:latest` +(built from `.gitea/docker/Dockerfile.ci-cpp` — Ubuntu 22.04 + Node 20 + cmake + +build-essential + libboost-dev + doxygen). + +### `.gitea/workflows/cpp-tests.yml` + +| Job | Trigger | Memory cap | What it does | +|---|---|---|---| +| `test-fast` | every push to `main` / `claude/**` / `feature/**` / `review/**` + every PR | 800 MB | Pure-math suite (Clausen, ImLi₂, hyper-ideal). Serial build (`-j1`) to avoid OOM. Eigen vendored, GTest via FetchContent. | +| `test-cgal` | commit message contains **`/test-cgal`** | 2000 MB | Full CGAL suite via `LOW_MEMORY_BUILD` (`-O0`, no PCH, unity batch 1, `--no-keep-memory`). Then `check-test-counts.sh` + `try_it.sh` smoke test. | +| `quality-gates` | commit message contains **`/quality-gates`** | 600 MB | License headers, CGAL conventions, codespell, shellcheck, coverage (gate currently in report-only mode, `SKIP_COVERAGE_GATE=1`). | + +> One keyword per commit — the Pi cannot sustain multiple Docker containers at +> once (`/ci-all` was removed for this reason). Example: +> `git commit -m "fix: correct angle formula /test-cgal"`. + +### Other eulernest workflows + +| File | Trigger | Purpose | Blocks merge? | +|---|---|---|---| +| `doc-build.yaml` | push to main branches + manual | Doxygen HTML + warning stats | No (`continue-on-error`) | +| `markdown-links.yml` | push + weekly cron (Mon 05:00 UTC) + manual | Link-rot check across docs | Yes on push | +| `doxygen-pages.yml` | manual only | Publish Doxygen HTML to Codeberg Pages (`tmoussa.codeberg.page/ConformalLabpp/`) | n/a | +| `perf-compile-time.yml` | manual only | Compile-time benchmark | n/a | +| `mirror-to-codeberg.yml` | push to `main` | Mirror all branches to Codeberg (see below) | n/a | + +--- + +## Codeberg (`codeberg`) — public mirror CI + +Codeberg's shared runners **cannot** pull the private `ci-cpp` image and are not +the `eulernest` Pi, so the Codeberg configs differ from Gitea in exactly two +ways: + +1. **Runner label** `docker` (Codeberg shared runners), not `eulernest`. +2. **Public base image**, with build tools `apt`-installed at run time: + - Woodpecker: `debian:bookworm` + - Forgejo Actions: `node:20-bookworm` (Node is needed by + `actions/checkout@v4`; cmake/g++/make are installed in the first step). + +Both run **only** `test-fast` — the pure-math suite. No CGAL/Boost/Wayland, so +they are fast (< 2 min) and headless. Eigen is vendored, GoogleTest is fetched +at configure time (Codeberg runners have network). A failing build or any +failing `ctest` turns the public CI badge red. + +| File | CI system | Enable via | +|---|---|---| +| `.woodpecker.yml` | Woodpecker | https://ci.codeberg.org → enable repo | +| `.forgejo/workflows/cpp-tests.yml` | Forgejo Actions | repo *Settings → Actions* (shared runner label `docker`) | + +> These configs are committed in the repo and reach Codeberg through the mirror +> — they are not maintained separately on Codeberg. + +--- + +## Mirror (eulernest → Codeberg) + +`.gitea/workflows/mirror-to-codeberg.yml` runs on every push to `main` and does +a `git push --mirror` from eulernest to +`codeberg.org/TMoussa/ConformalLabpp.git`. It uses two secrets: + +- `MIRROR_TOKEN` — read access to the eulernest source repo. +- `CODEBERG_TOKEN` — push access to the Codeberg mirror. + +The mirror is **one-way and authoritative-from-eulernest**: do not commit +directly on Codeberg, it will be overwritten on the next mirror run. + +--- + +## The one rule + +> **eulernest is the gate, Codeberg is the shop window.** +> Merge decisions are made on eulernest CI (full suite). Codeberg CI exists so +> the public repo also shows a green/red build status to outside readers. + +## See also + +- [dependencies.md](dependencies.md) — what each build mode requires. +- [project-structure.md](project-structure.md) — where the test targets live. +- [../api/tests.md](../api/tests.md) — per-suite test counts CI checks against. +- [../contributing.md](../contributing.md) — the git workflow that feeds CI. diff --git a/doc/contributing.md b/doc/contributing.md index 47003a3..d6b0363 100644 --- a/doc/contributing.md +++ b/doc/contributing.md @@ -13,11 +13,12 @@ with English. ## Git workflow - `main` is protected on `origin` (Gitea). Push to `dev`, then open a pull request. -- `codeberg/main` can be pushed to directly (public mirror, no CI). +- `codeberg/main` is the public mirror. It now also runs CI of its own + (Woodpecker + Forgejo Actions) — see [architecture/ci-cd.md](architecture/ci-cd.md). - Both remotes must stay in sync after every significant change: ```bash - git push origin HEAD:dev # triggers CI - git push codeberg main # updates public mirror + git push origin HEAD:dev # triggers eulernest CI (full suite, keyword-gated CGAL) + git push codeberg main # updates public mirror → triggers Codeberg CI (test-fast) ``` - Branch naming: `feature/`, `fix/`, `phase-` @@ -25,17 +26,30 @@ with English. ## CI -Two jobs run on push to `dev`/`main` or on pull requests: +The project runs CI on **two forges**. Full topology, runners, images and +trigger keywords are documented in [architecture/ci-cd.md](architecture/ci-cd.md). + +**eulernest Gitea** (`origin`, self-hosted Raspberry Pi / ARM64) — the +authoritative gate. On push to `dev`/`main` or a pull request: | Job | What it tests | Trigger | |---|---|---| | `test-fast` | pure-math tests, no Boost | all branches | -| `test-cgal` | full CGAL test suite | `main`, `dev`, PRs only | +| `test-cgal` | full CGAL test suite | commit message contains `/test-cgal` | +| `quality-gates` | license / codespell / shellcheck / CGAL conventions | commit message contains `/quality-gates` | -A PR is ready to merge when both jobs pass. +A PR is ready to merge when `test-fast` (and, for CGAL-touching work, +`test-cgal`) pass. See `.gitea/workflows/cpp-tests.yml` and +`.gitea/docker/Dockerfile.ci-cpp`. -The runner is a self-hosted Raspberry Pi (ARM64). See `.gitea/workflows/cpp-tests.yml` -and `.gitea/docker/Dockerfile.ci-cpp`. +**Codeberg** (`codeberg`, public mirror, shared runners) — a lightweight +`test-fast` mirror so the public repo also shows a build status. Defined twice, +once per CI system Codeberg offers: + +| File | CI system | +|---|---| +| `.woodpecker.yml` | Woodpecker CI (ci.codeberg.org) | +| `.forgejo/workflows/cpp-tests.yml` | Forgejo Actions | ---