# Forgejo CI Baseline

Created: 2026-05-23 20:34 EDT · Repo: `islandflow` · Branch: `lavender/forgejo-ci-baseline`

Beads islandflow-1gq Forgejo Actions Fast Validate Path Self-hosted Docker Runner

## Summary

Added a Forgejo-native CI baseline at `.forgejo/workflows/ci.yml` that runs the repo’s fast, high-signal Bun validation path on pull requests, pushes to `main`, and manual dispatches. The repo documentation now describes the required runner labels, what the workflow covers, what it intentionally leaves out, and how to rerun it from Forgejo.

## Changes Made

- Added the canonical Forgejo workflow file at `.forgejo/workflows/ci.yml`.
- Configured a single `validate` job that runs checkout, Bun bootstrap, `bun install --frozen-lockfile`, `bun test`, `bun run check:docker-workspace`, and `bun --cwd=apps/web run build`.
- Added workflow concurrency cancellation so stale branch and PR runs do not pile up.
- Used a fully qualified Forgejo-hosted checkout action URL: `https://data.forgejo.org/actions/checkout@v4`.
- Added a short CI section to `README.md` covering runner labels, scope, exclusions, and manual reruns.
- Synced the generated Docker workspace snapshot files after the repo’s own snapshot check revealed drift that would have made the new CI job fail immediately.

## Context

This first wave is aimed at early-stage confidence rather than full release automation. The chosen checks were already the strongest local signals in the repo, so the workflow stays fast enough for PR gating while still catching real regressions in tests, dependency shape, Docker workspace sync, and the production web build.

Forgejo’s current docs recommend `.forgejo/workflows` as the canonical workflow location and recommend fully qualified action URLs because an instance can change its default action source. The runner guidance also notes that checkout is a Node-based action, which is why the documented label uses a Node-capable Docker image.

## Important Implementation Details

- The workflow targets `runs-on: ubuntu-latest` so maintainers can back that label with a Docker image such as `ubuntu-latest:docker://node:20-bookworm`.
- Bun is installed explicitly inside the job rather than through another shared setup action. That keeps the baseline dependency surface smaller and avoids adding another remote action source to the first Forgejo CI pass.
- The workspace snapshot sync touched generated files under `deployment/docker/workspace-root`, including the mirrored manifest and lockfile, because `check:docker-workspace` enforces parity between the repo root and the deployment workspace snapshot.
- Existing `.github/workflows` files were left alone so GitHub-specific docs and notification behavior can continue separately without becoming the canonical CI path.

## Relevant Diff Snippets

.forgejo/workflows/ci.yml

    +name: CI
    +
    +on:
    +  pull_request:
    +  push:
    +    branches:
    +      - main
    +  workflow_dispatch:
    +
    +concurrency:
    +  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
    +  cancel-in-progress: true

README.md · CI section

    +## CI
    +
    +Forgejo Actions under `.forgejo/workflows` are the canonical CI path for this repository.
    +...
    +- `bun test`
    +- `bun run check:docker-workspace`
    +- `bun --cwd=apps/web run build`

deployment/docker/workspace-root/package.json

    +  "overrides": {
    +    "postcss": "^8.5.15",
    +    "tar": "^7.5.15",
    +    "tmp": "^0.2.5"
    +  },
    +  "dependencies": {
    +    "@pierre/diffs": "^1.2.2"
    +  }

These snippets render client-side with `@pierre/diffs` and include inline fallback text for offline viewing.

## Expected Impact for End-Users

There is no direct product-surface change for trading or replay users. The main effect is on contributor and maintainer experience: pull requests and mainline pushes can now get fast, consistent validation in Forgejo before heavier CI layers exist, which should reduce broken merges and make failures easier to interpret.

## Validation

- Passed: `ruby -e 'require "yaml"; YAML.load_file(".forgejo/workflows/ci.yml")'` (`yaml ok`).
- Passed: `bun install --frozen-lockfile`.
- Passed: `bun test` with `246 pass`, `0 fail`.
- Passed: `bun run check:docker-workspace` after syncing the generated deployment workspace snapshot.
- Passed: `bun --cwd=apps/web run build`.
- Not completed locally: a runner-like Docker smoke test could not be performed from this workstation because the local Docker daemon socket was unavailable at the time of validation.
- Forgejo-side validation pending push: workflow discovery in the Actions UI, manual dispatch, and PR-trigger confirmation must happen against the pushed branch on the Forgejo instance.

## Issues, Limitations, and Mitigations

- The workflow currently installs Bun during each run, which adds a small amount of startup cost. Mitigation: this keeps the first baseline explicit and avoids another remote setup action dependency.
- The local environment could not fully emulate the self-hosted Docker runner because Docker was not reachable from this machine. Mitigation: the workflow syntax and repo checks were validated locally, and the remaining discovery/dispatch checks are clearly called out for Forgejo-side verification.
- The generated deployment workspace snapshot had already drifted before this change. Mitigation: the new CI path now includes `check:docker-workspace`, and the snapshot was synced in the same turn so the baseline starts green.

## Follow-up Work

- `islandflow-3ys`: expand Forgejo CI beyond the fast validate path with Docker builds, service-container integration coverage, and later deploy or release automation.
- After this branch is pushed, manually dispatch the `CI` workflow from Forgejo and confirm runner label resolution plus checkout/Bun bootstrap on the self-hosted runner.
- If Bun setup time becomes noticeable, consider a later follow-up that either bakes Bun into the CI image or introduces a deliberately chosen cache/setup strategy after the baseline proves stable.