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

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
REUSE-WP-0019	workplan	Forgejo-native federation automation and reuse telemetry	infotech	reuse-surface	active	claude-code	helix-forge	2026-07-06	2026-07-06	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

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

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

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

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

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

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)