From bd7bd81cc0046b9e0461933a87c2bca7749d1b0e Mon Sep 17 00:00:00 2001 From: ErenAri Date: Thu, 2 Jul 2026 02:35:56 +0300 Subject: [PATCH] feat(ci): publish the quirk-library matrix to GitHub Pages weekly MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Turn compatibility-matrix-publish from a manual self-hosted lane that validated a dev fixture into the public compatibility matrix: - runs on a stock GitHub-hosted runner (hosted ubuntu-latest exposes /dev/kvm; TCG fallback otherwise) — no self-hosted runner needed; - weekly schedule (Tue 06:00 UTC) + manual dispatch; - validates matrices/quirk-library.yaml against a contrast pair: ringbuf-modern (shows the version-lies story: fails upstream <5.8, passes RHEL's backported 4.18, fails Amazon's 4.14) and simple-pass (proves the failures are feature gaps, not broken kernels); - deploys the generated static site to GitHub Pages on every scheduled run (Pages enabled, build_type=workflow): https://kernel-guard.github.io/bpfcompat/ - README + quirk-library doc link the public matrix. Evidence upload keeps the allowlist-only path policy (never .bpfcompat/runs/** wholesale — per-run SSH keys live there). Co-Authored-By: Claude Opus 4.8 --- .../compatibility-matrix-publish.yml | 102 +++++++++++++----- README.md | 4 +- docs/kernel-quirk-library.md | 6 ++ 3 files changed, 82 insertions(+), 30 deletions(-) diff --git a/.github/workflows/compatibility-matrix-publish.yml b/.github/workflows/compatibility-matrix-publish.yml index 54b540e..e37eb92 100644 --- a/.github/workflows/compatibility-matrix-publish.yml +++ b/.github/workflows/compatibility-matrix-publish.yml @@ -1,15 +1,29 @@ name: compatibility-matrix-publish -# Publishes release-style compatibility evidence from a self-hosted KVM runner. -# This is intentionally separate from cheap PR CI because it boots real VMs. +# Publishes the public compatibility matrix: the library of known-tricky +# vendor kernels (matrices/quirk-library.yaml) validated against a contrast +# pair of artifacts, regenerated weekly and deployed to GitHub Pages. +# +# The pair is chosen to make the "kernel version != eBPF feature support" +# story visible in one table: +# - ringbuf-modern: fails upstream < 5.8 but PASSES AlmaLinux 8's 4.18 +# (RHEL backport) while FAILING Amazon Linux 2's 4.14 (no backport); +# - simple-pass: loads everywhere, proving the failures above are feature +# gaps, not broken kernels. +# +# Runs on a stock GitHub-hosted runner (/dev/kvm is exposed; TCG fallback +# otherwise). Non-blocking by design: scheduled + manually dispatched. on: workflow_dispatch: inputs: deploy_pages: - description: Deploy generated compatibility site to GitHub Pages. Requires Pages to be enabled for the repo. + description: Deploy generated compatibility site to GitHub Pages. required: false - default: "false" + default: "true" + schedule: + # Weekly, Tuesday 06:00 UTC + - cron: "0 6 * * 2" # Least privilege at the top; write scopes are granted per-job below. permissions: @@ -22,8 +36,8 @@ concurrency: jobs: publish-compatibility-matrix: name: Publish compatibility matrix - runs-on: [self-hosted, linux, x64] - timeout-minutes: 60 + runs-on: ubuntu-latest + timeout-minutes: 90 permissions: contents: write # attach matrix assets to tag releases pages: write # deploy the compatibility site to GitHub Pages @@ -32,37 +46,61 @@ jobs: steps: - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6 - - name: Verify KVM availability + - name: Report KVM acceleration status shell: bash run: | set -euo pipefail - test -e /dev/kvm || (echo "::error::/dev/kvm not found" && exit 1) + if [[ -e /dev/kvm ]]; then + echo "::notice::/dev/kvm present - VM validation is hardware-accelerated." + # Some hosted images expose /dev/kvm but the runner user is not in + # the kvm group; loosen perms so QEMU can open it. + sudo chmod 0666 /dev/kvm || true + ls -l /dev/kvm || true + else + echo "::warning::/dev/kvm not found - falling back to TCG software emulation (slower, still correct)." + fi - - name: Build validator and fixture artifacts + - name: Install host dependencies shell: bash run: | set -euo pipefail - make validator-static - make examples + sudo apt-get update + sudo apt-get install -y --no-install-recommends \ + qemu-system-x86 qemu-utils clang llvm libbpf-dev libelf-dev zlib1g-dev \ + pkg-config jq - - name: Fetch dev VM image + - name: Build validator and fixture artifacts shell: bash run: | set -euo pipefail - make vm-ubuntu-22 + make validator-static + make examples - - name: Run bpfcompat action + - name: Validate ringbuf-modern across the quirk library uses: ./ with: - artifact: examples/functional-execve/functional_execve.bpf.o - manifest: examples/functional-execve/manifest-dev-one.yaml - matrix: matrices/dev-one.yaml - out: reports/release-functional-execve.json - markdown: reports/release-functional-execve.md - timeout: 8m - concurrency: "1" + artifact: examples/ringbuf-modern/ringbuf_modern.bpf.o + matrix: matrices/quirk-library.yaml + validation-mode: load_attach + out: reports/quirk-library-ringbuf-modern.json + markdown: reports/quirk-library-ringbuf-modern.md + timeout: 12m + concurrency: "2" build: "true" + - name: Validate simple-pass across the quirk library + # Images are cached from the first run, so this pass is much faster. + uses: ./ + with: + artifact: examples/simple-pass/simple_pass.bpf.o + matrix: matrices/quirk-library.yaml + validation-mode: load_attach + out: reports/quirk-library-simple-pass.json + markdown: reports/quirk-library-simple-pass.md + timeout: 12m + concurrency: "2" + build: "false" + - name: Generate static compatibility index if: always() shell: bash @@ -71,7 +109,7 @@ jobs: if [[ "${GITHUB_REF_TYPE:-}" == "tag" ]]; then version="${GITHUB_REF_NAME}" else - version="manual-${GITHUB_RUN_ID}" + version="$(date -u +%Y%m%d)-run${GITHUB_RUN_ID}" fi export BPFCOMPAT_COMPATIBILITY_VERSION="$version" bash scripts/publish-compatibility-site.sh reports public/compatibility @@ -82,11 +120,15 @@ jobs: with: name: bpfcompat-compatibility-matrix-${{ github.run_id }} if-no-files-found: warn + # Allowlist only — never `.bpfcompat/runs/**` wholesale: the per-run + # dir also holds the generated SSH private key (id_ed25519), the + # cloud-init seed, and the disk overlay, none of which belong in a + # downloadable artifact. path: | public/compatibility/index.html public/compatibility/index.md - reports/release-functional-execve.json - reports/release-functional-execve.md + reports/quirk-library-*.json + reports/quirk-library-*.md .bpfcompat/runs/**/targets/**/serial.log .bpfcompat/runs/**/targets/**/libbpf.log .bpfcompat/runs/**/targets/**/validator-result.json @@ -99,8 +141,10 @@ jobs: set -euo pipefail tar -czf "bpfcompat-compatibility-${GITHUB_REF_NAME}.tgz" \ public/compatibility \ - reports/release-functional-execve.json \ - reports/release-functional-execve.md + reports/quirk-library-ringbuf-modern.json \ + reports/quirk-library-ringbuf-modern.md \ + reports/quirk-library-simple-pass.json \ + reports/quirk-library-simple-pass.md - name: Attach compatibility evidence to GitHub release if: startsWith(github.ref, 'refs/tags/v') @@ -115,15 +159,15 @@ jobs: gh release upload "$GITHUB_REF_NAME" "bpfcompat-compatibility-${GITHUB_REF_NAME}.tgz" --clobber - name: Configure Pages - if: github.event_name == 'workflow_dispatch' && inputs.deploy_pages == 'true' + if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.deploy_pages == 'true') uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6 - name: Upload Pages artifact - if: github.event_name == 'workflow_dispatch' && inputs.deploy_pages == 'true' + if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.deploy_pages == 'true') uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5 with: path: public/compatibility - name: Deploy Pages - if: github.event_name == 'workflow_dispatch' && inputs.deploy_pages == 'true' + if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.deploy_pages == 'true') uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5 diff --git a/README.md b/README.md index cf1fa5c..748048c 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,9 @@ bpfcompat test --command '$BPFCOMPAT_BIN --self-test' --command-binary ./build/l --matrix matrices/quirk-library.yaml --out report.json ``` -See [docs/kernel-quirk-library.md](docs/kernel-quirk-library.md). +See [docs/kernel-quirk-library.md](docs/kernel-quirk-library.md). The library +is re-validated weekly and the resulting matrix is published at +[kernel-guard.github.io/bpfcompat](https://kernel-guard.github.io/bpfcompat/). ### Distributions covered diff --git a/docs/kernel-quirk-library.md b/docs/kernel-quirk-library.md index be5987e..deb2410 100644 --- a/docs/kernel-quirk-library.md +++ b/docs/kernel-quirk-library.md @@ -7,6 +7,12 @@ no-BTF kernels, vendor rebases, and program-variant fallback bands. Every entry is a kernel bpfcompat **actually boots** (real vendor cloud image in a disposable VM) and has evidence for — not a version string we inferred from. + +**Public matrix:** the library is re-validated weekly against a contrast pair of +artifacts and published at +[kernel-guard.github.io/bpfcompat](https://kernel-guard.github.io/bpfcompat/) +(the `compatibility-matrix-publish` workflow). + Run the whole library against a `.bpf.o` *or* your own loader (command mode): ```bash