# 08. CI/CD Strategy (Gitea-Based)

## 1. Objectives

- Keep release cadence high without bypassing security checks.
- Provide deterministic, reproducible artifacts for Hub, Safety components, and Provisioner.
- Enforce policy gates (security invariants, banned tools, contract compatibility) in CI.

## 2. Platform Baseline

- CI engine: **Gitea Actions** with self-hosted **act_runner**.
- Artifact registry: private container registry (`code.letsbe.solutions/...`).
- Deployment target:
  - Control plane: Docker hosts (EU + US)
  - Tenant plane: provisioner-managed customer VPS rollout jobs

## 3. Branch And Release Model

- `main`: releasable at all times.
- short-lived feature branches.
- release tags: `hub/vX.Y.Z`, `safety/vX.Y.Z`, `provisioner/vX.Y.Z`.
- hotfix branch only for production incidents, merged back to `main` immediately.

## 4. Pipeline Stages

## 4.1 Pull Request Pipeline

1. `lint-typecheck`
2. `unit-tests`
3. `integration-tests`
4. `contract-tests`
5. `security-scan` (SAST, dependency vulnerabilities, secret scan)
6. `policy-checks`:
   - banned stack/reference detector (`n8n`, deprecated deploy targets)
   - no plaintext credentials in artifacts/config
7. `build-preview-images`

## 4.2 Main Branch Pipeline

1. re-run all PR checks
2. build immutable release images
3. generate SBOMs
4. image signing (cosign/sigstore-compatible)
5. push to registry with digest pins
6. deploy to `dev` automatically

## 4.3 Promotion Pipelines

- `promote-staging`: manual approval gate + smoke tests
- `promote-prod-eu`: manual approval + canary checks
- `promote-prod-us`: separate manual gate after EU health confirmation

## 5. Tenant Rollout Pipeline

Separate workflow for tenant-plane updates:

- policy-only rollout job
- wrapper package rollout job
- OpenClaw version rollout campaign

Rollout controller enforces:

- canary percentages
- halt thresholds
- automated rollback trigger execution

## 6. Required Checks Per Package

| Package | Required Jobs |
|---|---|
| Hub | lint, unit, integration, Prisma migration check, API contract tests |
| Safety Wrapper | unit, hook integration (OpenClaw pinned tag), redaction/gating invariants |
| Egress Proxy | redaction corpus tests, outbound policy tests, perf checks |
| Provisioner | shellcheck, template checks, disposable VPS smoke run |
| Mobile | typecheck, unit/UI tests, API contract tests, build verification |
| Website | lint/typecheck, onboarding flow tests, pricing/quote tests |

## 7. Example Gitea Workflow Skeleton

```yaml
name: pr-checks
on: [pull_request]

jobs:
  lint-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint && pnpm typecheck
      - run: pnpm test:unit

  security-policy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm test:security-invariants
      - run: ./scripts/ci/check-banned-references.sh
      - run: ./scripts/ci/check-no-plaintext-secrets.sh
```

## 8. Secrets And Runner Security

- Gitea secrets scoped by environment (`dev/staging/prod`).
- Runner hosts are isolated and ephemeral where possible.
- No production credentials in PR jobs.
- OIDC-based short-lived cloud/provider credentials preferred over long-lived static tokens.

## 9. Change Management Gates

Security-critical paths require extra gate:

- files under `safety-wrapper/`, `egress-proxy/`, `provisioner/scripts/credentials*`
- mandatory 2 reviewers
- security test suite pass required
- no force-merge override

## 10. Metrics For CI/CD Quality

Track weekly:

- median PR cycle time
- flaky test rate
- change failure rate
- mean time to rollback
- canary abort count

Use these metrics in weekly engineering ops review to keep speed/quality balance aligned with launch target.