reuse-surface/workplans/REUSE-WP-0019-forgejo-automation-and-telemetry.md

---
id: REUSE-WP-0019
type: workplan
title: "Forgejo-native federation automation and reuse telemetry"
domain: infotech
repo: reuse-surface
status: active
owner: claude-code
topic_slug: helix-forge
created: "2026-07-06"
updated: "2026-07-06"
state_hub_workstream_id: "569be717-34f8-4039-bb26-497685f60159"
---

# Forgejo-native federation automation and reuse telemetry

Federation compose is on-demand and the hub serves whatever was last composed;
roster sweeps are manual; reliability evidence is structural (CI exists) rather
than observed (someone reused it and it worked). This workplan makes the
registry **live** (event-driven recompose) and **evidence-backed** (reuse
telemetry feeding the R axis).

**Platform constraint:** the forge is transitioning **Gitea → Forgejo**. All
new automation attaches to Forgejo (webhooks, Forgejo Actions, API tokens) —
nothing new is built against Gitea. Existing raw URLs
(`https://gitea.coulomb.social/...`) and `.gitea/workflows/` must migrate or
be made host-agnostic. Forgejo is Gitea-API-compatible, so migration is mostly
host/path configuration, but every hardcoded `gitea.` reference is a liability.

**Depends on:** REUSE-WP-0017 (content worth refreshing), REUSE-WP-0018-T01
telemetry schema (shared). Closes SCOPE "not possible yet" item *automatic hub
refresh* and moves reliability evidence beyond structural.

## Design principles

1. **Host-agnostic first** — a single `forge_base_url` configuration
   (env/config + hub setting) replaces hardcoded hosts; the Forgejo cutover
   becomes a one-line change per surface.
2. **Webhook triggers, compose stays pull-based** — the webhook only marks the
   hub's composed index stale and triggers recompose from published raw URLs;
   no push-parsing of payloads into registry state.
3. **Degrade to schedule** — if webhooks are unavailable, a scheduled Forgejo
   Actions job recomposes on an interval; freshness is monitored either way.
4. **Telemetry is append-only and low-ceremony** — reuse events are JSONL
   facts (who consumed what, when, outcome); aggregation derives `reused_by`
   relations and R-axis evidence citations, never hand-edited.

## Dependencies

| Dependency | Owner | Notes |
|---|---|---|
| Forgejo instance + admin | Bernd / infra | webhook config, org-level token, Actions runners |
| Gitea→Forgejo cutover plan | infra | final hostname, raw URL scheme, redirect window |
| Hub deployment (reuse.coulomb.social) | reuse-surface / railiance | new endpoint + config rollout |
| REUSE-WP-0018-T01 | reuse-surface | shared telemetry/outcome schema |
| plan-check adoption | ecosystem | telemetry volume comes from WP-0018-T05 rollout |

---

## Forge Host Abstraction And URL Migration Inventory

```task
id: REUSE-WP-0019-T01
status: todo
priority: high
state_hub_task_id: "4a187b56-bff9-4097-abd0-b423e7bf9442"
```

- Inventory every hardcoded `gitea.coulomb.social` / `.gitea/` reference:
  `sources.yaml` (60 raw URLs), hub registrations, establish/publish-check
  defaults, docs, templates, CI workflows
- Introduce `REUSE_SURFACE_FORGE_BASE_URL` (env + hub config); derive raw
  index URLs from `{base}/{org}/{repo}/raw/{branch}/registry/indexes/capabilities.yaml`
- Migration command: `reuse-surface federation migrate-host --from <old> --to <new>`
  rewriting sources.yaml + hub registrations via the hub API
- Check whether the config-atlas 303 (WP-0017-T06) is a symptom of the host
  transition; coordinate findings
- Tests: URL derivation, migrate-host dry-run

## Hub Recompose Endpoint And Webhook Receiver

```task
id: REUSE-WP-0019-T02
status: todo
priority: high
state_hub_task_id: "691eb32a-6f20-4a2a-b9ff-0ae427b659aa"
```

- Hub service (`reuse_surface/serve`): `POST /v1/recompose` (token-auth) —
  marks index stale and triggers recompose from registered raw URLs
- `POST /v1/webhooks/forgejo`: validates Forgejo webhook signature
  (`X-Forgejo-Signature`, secret from env), accepts push events, triggers
  recompose only when the pushed commits touch `registry/indexes/`
- Debounce/coalesce concurrent triggers; `GET /v1/federated` gains
  `composed_at` + `stale` fields
- Extend `specs/FederationHubAPI.md`; pytest with signed fixture payloads

## Forgejo Webhook Rollout And Scheduled Fallback

```task
id: REUSE-WP-0019-T03
status: wait
priority: medium
state_hub_task_id: "aa9e9f80-b878-490c-832e-515d8cbbbb60"
```

Blocked on T02 deploy and Forgejo instance availability.

- Org-level Forgejo webhook (single config, all repos) → hub
  `/v1/webhooks/forgejo`, push events only
- Fallback: Forgejo Actions scheduled workflow (cron) in this repo calling
  `POST /v1/recompose`; also serves repos during any Gitea-remnant window
- Migrate this repo's CI `.gitea/workflows/ci.yml` → `.forgejo/workflows/ci.yml`
  (Forgejo Actions; verify runner labels); document the pattern for siblings
- Verify end-to-end: index change in a sibling repo → hub `composed_at`
  advances without manual compose

## Reuse Telemetry Store And Recording

```task
id: REUSE-WP-0019-T04
status: todo
priority: medium
state_hub_task_id: "c8e9064e-5c39-4c84-80e9-8b255f8edaec"
```

- Implement the shared schema from WP-0018-T01: reuse events
  `{ts, consumer_repo, capability_id, verdict, outcome?, source: plan-check|manual|hub}`
- Hub: `POST /v1/reuse-events` (token-auth) + local JSONL fallback when hub
  unreachable; `GET /v1/reuse-events?capability_id=` for aggregation
- `plan-check --record-outcome` (WP-0018) posts here; manual
  `reuse-surface record-reuse` for retroactive facts
- Privacy/scope: repo slugs and capability ids only — no code, no secrets

## Telemetry Aggregation Into R-Axis Evidence

```task
id: REUSE-WP-0019-T05
status: wait
priority: medium
state_hub_task_id: "f0282cfa-0a71-4b46-a558-80b51ef04fa7"
```

Blocked on T04 plus initial event volume.

- `reuse-surface report reuse`: per-capability consumer counts, outcomes,
  last-used; feeds `reused_by` relation suggestions via the WP-0016
  maintain/patch pipeline (evidence-gated, never silent promotion)
- Maturity standard note: what observed-reuse evidence counts toward R2/R3+
  (`specs/CapabilityMaturityStandard.md` amendment)
- Catalog + graph surface consumer counts

## Freshness Monitoring, Docs, SCOPE

```task
id: REUSE-WP-0019-T06
status: todo
priority: low
state_hub_task_id: "a9f44d45-91e2-4b43-909f-30a5f906cf3b"
```

- `reuse-surface stats`: hub `composed_at` age + stale flag; CI informational
  check warns when the hub index is older than N days
- `docs/RegistryFederation.md` + `docs/deploy/reuse-kubernetes.md`: webhook
  setup, recompose endpoint, Forgejo token handling (route credentials per
  credential-routing rules — no secrets in repo)
- `SCOPE.md`: flip "automatic hub refresh" to possible; update federation
  posture

---

## Acceptance

- [ ] No hardcoded forge host in code or sources.yaml; `migrate-host` tested
- [ ] Push to a sibling repo's `registry/indexes/` recomposes the hub index without manual action (webhook), with scheduled fallback in place
- [ ] This repo's CI runs on Forgejo Actions (`.forgejo/workflows/`)
- [ ] Reuse events recordable via hub API and CLI; `report reuse` aggregates them
- [ ] R-axis evidence rules for observed reuse documented in the maturity standard
- [ ] Hub freshness visible (`composed_at`, stale flag) in API and stats

## Out of scope

- Operating the Forgejo instance or the Gitea→Forgejo data migration itself
- Multi-replica/Postgres hub posture (separate managed-platform track)
- Blocking CI gates on registry freshness in sibling repos
- ActivityPub/Forgejo-native federation features (our federation layer stays raw-URL based)