ci: run the integration tests against a real gVisor daemon

Closes #3.

CI compiled the integration suite and never ran it, so a green run graded
pkg/docker at 17.7% unit coverage while the engine's actual verification —
containment, blocked egress, the reaper, the resource caps under attack —
ran only when someone remembered to do it locally.

The blocker was assumed to be gVisor needing hardware a hosted runner does
not have. It does not: the systrap platform uses seccomp and needs neither
KVM nor nested virtualisation, so ubuntu-latest can register runsc. That
also keeps the suite off a self-hosted runner, which on a public repo would
mean executing a stranger's pull request on our own hardware.

Registration is asserted in its own step, and asserted by booting a guest
rather than by reading the runtime list: openblox refuses to fall back to
runc, so an absent or broken runtime would otherwise surface as fifty
identical ErrRuntimeUnavailable failures instead of one legible message.
Per the issue, it fails loudly rather than skipping — a silent skip would
rebuild exactly the false confidence being removed.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Lutherwaves

.github/workflows/ci.yml

@@ -81,9 +81,6 @@ jobs:
           CGO_ENABLED: '1'
         run: go test -race -cover -v ./...
 
-  # Integration tests need a gVisor-capable host, which hosted runners are not.
-  # Compiling them on every PR is what stops them rotting between the rare runs
-  # on a self-hosted box — a test that no longer builds is a test nobody runs.
   vuln:
     name: Vulnerabilities
     runs-on: ubuntu-latest
@@ -124,3 +121,65 @@ jobs:
         env:
           CGO_ENABLED: '0'
         run: go build -tags integration ./... && go vet -tags integration ./...
+
+  # The engine is only actually verified by the integration suite: containment on
+  # a live container, egress blocked, the reaper, the resource caps under attack.
+  # Everything else in this file grades a package whose unit coverage is 17.7%.
+  #
+  # This was long assumed to need a self-hosted box. It does not: gVisor's systrap
+  # platform uses seccomp and does not require KVM or nested virtualisation, so a
+  # standard hosted runner can register runsc. That also keeps the suite off a
+  # self-hosted runner, which for a public repo would mean executing a stranger's
+  # PR on our own hardware.
+  integration:
+    name: Integration Tests (gVisor)
+    runs-on: ubuntu-latest
+    needs: lint
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 1
+          persist-credentials: false
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install gVisor
+        run: |
+          set -euo pipefail
+          curl -fsSL https://gvisor.dev/archive.key \
+            | sudo gpg --dearmor -o /usr/share/keyrings/gvisor-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/gvisor-archive-keyring.gpg] https://storage.googleapis.com/gvisor/releases release main" \
+            | sudo tee /etc/apt/sources.list.d/gvisor.list > /dev/null
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq runsc
+          # The package's postinst registers the runtime with dockerd itself;
+          # runtimes are reloadable, so this needs no daemon restart.
+          sudo systemctl reload docker
+          runsc --version
+
+      # openblox refuses to fall back to runc, so without this the whole suite
+      # would fail on ErrRuntimeUnavailable rather than on anything it tests.
+      # Asserted as its own step so that failure is legible instead of arriving
+      # as fifty identical test errors.
+      - name: Verify runsc is registered
+        run: |
+          set -euo pipefail
+          docker info --format '{{range $k, $v := .Runtimes}}{{$k}} {{end}}' | tr ' ' '\n' | grep -qx runsc
+          # Prove it actually boots a guest, not merely that it is listed: a
+          # registered-but-broken runtime is the failure this guards against.
+          kernel=$(docker run --rm --runtime=runsc --network=none alpine:3.20 uname -r)
+          echo "guest kernel: $kernel"
+          case "$kernel" in
+            *gvisor*) ;;
+            *) echo "::error::runsc ran but the guest is not gVisor ($kernel)"; exit 1 ;;
+          esac
+
+      # -count=1 because these assert against live host state (process counts,
+      # free memory) that a cached PASS would silently stand in for.
+      - name: Run integration tests
+        env:
+          CGO_ENABLED: '0'
+        run: go test -tags integration -count=1 -v -timeout 20m ./...

README.md

@@ -7,7 +7,7 @@
 
 [![CI](https://github.com/blox-eng/openblox/actions/workflows/ci.yml/badge.svg)](https://github.com/blox-eng/openblox/actions/workflows/ci.yml)
 [![Tests](https://img.shields.io/endpoint?url=https://openblox.sh/badges/tests.json)](https://github.com/blox-eng/openblox/actions/workflows/ci.yml)
-[![Integration tests](https://img.shields.io/endpoint?url=https://openblox.sh/badges/integration.json)](https://github.com/blox-eng/openblox/issues/3)
+[![Integration tests](https://img.shields.io/endpoint?url=https://openblox.sh/badges/integration.json)](https://github.com/blox-eng/openblox/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/endpoint?url=https://openblox.sh/badges/coverage.json)](https://github.com/blox-eng/openblox/issues/10)
 [![Lines of Go](https://img.shields.io/endpoint?url=https://openblox.sh/badges/loc.json)](ARCHITECTURE.md)
 [![Go Reference](https://pkg.go.dev/badge/github.com/blox-eng/openblox.svg)](https://pkg.go.dev/github.com/blox-eng/openblox)
@@ -118,13 +118,12 @@ size, test counts, and coverage cannot drift from the code that produced them.
 Two direct dependencies (`docker/docker` and `containerd/errdefs`). Every release
 publishes a multi-architecture sandbox image with an SBOM and build provenance.
 CI runs lint, tests, and `govulncheck`, gating on newly reachable
-vulnerabilities.
+vulnerabilities. The integration suite runs there too, against a real gVisor
+daemon on a hosted runner — including the adversarial cases that try to break
+the resource caps.
 
-Honest about the gaps: the integration suite compiles in CI but does not run
-there — it needs a host with Docker and `runsc`, so it runs locally
-([#3](https://github.com/blox-eng/openblox/issues/3)). Using openblox today also
-means giving your service access to the Docker socket, which is root-equivalent
-on the host; closing that is
+Honest about the gaps: using openblox today means giving your service access to
+the Docker socket, which is root-equivalent on the host; closing that is
 [#2](https://github.com/blox-eng/openblox/issues/2), the most consequential open
 issue. The [open issues](https://github.com/blox-eng/openblox/issues) are the
 honest roadmap.