# CASAN CI Guide (Gitea Actions)

Wire the CASAN governance gate into your project's CI so every push/PR is governed.

## 1. Add the workflow
DevKit `install.sh` already drops `.gitea/workflows/casan-ci.yml`. To add manually, copy the
template:
```bash
cp packages/casan-devkit/templates/gitea-workflow/ci.yml .gitea/workflows/casan-ci.yml
```

## 2. What it runs
```yaml
- bash packages/casan-harness/scripts/bash/ci-harness-gate.sh   # all governance suites
- bash packages/casan-harness/scripts/bash/verify-audit-chain.sh
- bash packages/casan-harness/scripts/bash/sign-policy-bundle.sh verify
```

## 3. Environment knobs
| Var | Default | Use |
|---|---|---|
| `CASAN_CI_RUN_FRONTEND` | 0 | 1 if you have a frontend workspace |
| `CASAN_CI_RUN_BACKEND` | 0 | 1 to run backend tests |
| `CASAN_CI_RUN_INFRA_LAB` | 0 | 1 to run the Docker infra lab |
| `CASAN_CI_STEP_TIMEOUT_SEC` | 600 | raise to 1200 — some suites are model-backed and run ~450s; 600 flakes under load |
| `CASAN_CI_SUITE_FILTER` | — | regex to run a subset of suites |
| `CASAN_DOMAIN_ROOT` | apps/okr/domain | point at your project's domain |

## 4. Runner
Uses `runs-on: ci-runner` (a self-hosted Gitea Actions runner). To set one up on your host,
see `.gitea/vps-setup-runbook.md` and `scripts/setup-ci-runner.sh`. The runner needs
`bash`, `python3`, `openssl` (and `node`/`npm` only if you enable apps/okr/frontend/backend tests).

## 5. Expected result
`CI_GATE_SUMMARY PASS=<n> FAIL=0 SKIP=<k>`. Any FAIL fails the job (exit 1). The gate is
**fail-closed**: missing signatures/policy in enforced mode (`CASAN_PROFILE=prod` or
`CASAN_VERIFY_STRICT=1`) also fail.

## 6. This repo's own CI
The source hub's active pipeline is `.gitea/workflows/ci.yml` (frontend tests → security
gate → deploy). It already runs the gate from the promoted root layout
(`packages/casan-harness/...`). Use it as a worked example.

## Tips
- Keep the gate green as an invariant; every new control must ship a fail-able adversarial test.
- Do not stage runtime log artifacts (`.specify/logs`, evidence) produced by gate runs.
- For a quick local pre-push check: `bin/casan gate` (or a filtered subset).