corp-v1-channel-architecture/references/gitea-actions-evidence-triage.md

Gitea Actions evidence triage

Use this when a documentation PR or default-branch Action is marked failed but repository validation succeeds locally. The goal is to distinguish code/content failure from runner infrastructure failure without weakening the exact-head gate.

Evidence sequence

1. Record the remote default branch SHA and, for a PR, its exact remote head/base SHAs. Do not validate an unpushed local commit as though it were the PR artifact.
2. Query the repository Action tasks and identify the entry whose head_sha exactly matches the commit under review. Preserve task ID, run number, status, and run URL. Treat the tasks endpoint as paginated: a small limit can omit an older still-valid exact-head task after other branches produce newer runs. Increase the limit or paginate before declaring that exact-head CI is absent; if a prior report preserved a run ID, query that immutable run directly.
3. Immediately preserve the numeric run_id from the matching task's run URL. Poll /actions/runs/{run_id} for status and conclusion, then query its jobs. Do not depend on repeatedly rediscovering the task by SHA: completed tasks may disappear from the tasks listing or be displaced by later activity even though the run remains available by ID. Gitea commonly exposes these paths:
   • /api/v1/repos/{owner}/{repo}/actions/tasks?limit=...
   • /api/v1/repos/{owner}/{repo}/actions/runs/{run_id}
   • /api/v1/repos/{owner}/{repo}/actions/runs/{run_id}/jobs
   • /api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}/logs
4. Confirm the terminal run and every relevant job still report the exact expected head_sha; preserve run ID, job ID, conclusion, timestamps, and step conclusions. If a tasks-list poll returns empty after previously finding the match, query the preserved run ID before concluding that CI evidence is missing.
5. Determine the earliest failed phase:
   • checkout or later command output with a repository error: content/build evidence;
   • image pull/container creation/runner startup with no checkout or repository command: infrastructure evidence;
   • timeout/cancellation: report the last completed phase and do not infer repository failure.
6. Independently validate the exact remote commit in a clean detached checkout/worktree using the repository's frozen-lockfile install, full validator/test/typecheck/build command, and git diff --check.
7. Report remote CI and local validation separately. A local pass does not turn remote exact-head CI green; an infrastructure failure does not prove the repository content failed.
8. Keep the verdict partially in sync when required remote build/render evidence is unavailable or failed, unless project policy explicitly allows a different disposition. State the smallest remediation: rerun exact-head CI or repair runner infrastructure, then re-read the remote terminal result.

Concurrent-branch safety

If another channel worker is actively correcting the same PR branch:

• do not create a competing Architecture PR;
• compare the remote PR head with local work before making claims;
• describe unpushed commits or working-tree fixes as ongoing local work, never as delivered remediation;
• wait for the corrected remote head and its own exact-head CI before completion.

Reporting checklist

• default branch and SHA;
• PR URL, head/base SHA, mergeability, and remote changed-file scope;
• exact task/run/job IDs and failure phase;
• clean exact-commit local command results;
• browser/render checks performed or explicitly not rerun;
• approval gate under the active authority contract unchanged by CI, review, merge, or local validation; treat it as human-only only when the invocation explicitly narrows authority.