--- name: gitea-fix-ci description: Use when a user asks to debug or fix failing Gitea Actions, Gitea PR checks, or CI workflow runs for a Gitea-hosted repository. --- # Gitea Fix CI ## Overview Diagnose failing Gitea Actions from the pull request or workflow run, extract the smallest useful failure context, then propose a fix plan before changing code. Core principle: CI logs are evidence; do not guess from the red status alone. This is not a standalone executor. It guides use of `tea`, local `git`, and the Gitea API from the current workspace. ## When to Use - A Gitea-hosted repository has failing Gitea Actions or PR checks - The user asks to inspect a failed workflow run, job, or CI status - The user asks to fix CI after a push, branch update, or pull request update - Local tests pass but remote Gitea Actions fail ## When Not to Use - The repository is not hosted on Gitea or Forgejo-compatible infrastructure - The failure belongs to an external CI provider and only links out from Gitea - The user only wants a local test or lint run - Credentials, tokens, or network access are unavailable and the user has not provided the failing log text ## Inputs - Repository path, defaulting to the current workspace - Gitea base URL and repository owner/name, from `git remote -v` when possible - Pull request number, branch, commit SHA, or workflow run ID - Authentication method: `tea` login profile, `GITEA_TOKEN` for API requests, or an existing git credential for the Gitea web fallback - Any pasted CI log if remote access is unavailable ## Procedure 1. **Baseline local state** - Record `git status --short`, current branch, and latest commit SHA. - Identify the Gitea remote URL and owner/repo. - Do not modify files while gathering CI evidence. 2. **Verify Gitea access** - Prefer `tea` if it is installed and authenticated: - `tea login list` - `tea actions runs list --status failure --branch ` - `tea actions runs view ` - `tea actions runs logs --job ` - `tea pulls view ` - If `tea` is unavailable or lacks an Actions command for the installed version, use the Gitea API directly. - Check `/api/v1/version` and `/swagger.v1.json` when API behavior is unclear. Gitea 1.21 exposes Actions pages but not workflow run/job/log API endpoints. - Never print tokens. Pass API tokens through environment variables. 3. **Find failing workflow runs** - For a known run ID, fetch that run directly. - Otherwise list recent workflow runs filtered by branch, event, status, or commit SHA. - API patterns: - `GET /api/v1/repos///actions/runs` - `GET /api/v1/repos///actions/runs/` - `GET /api/v1/repos///actions/runs//jobs` - Web fallback for older Gitea: - `GET ///actions` - Parse `///actions/runs/` links and status labels. - Treat `failure`, `cancelled`, and missing required checks differently. Cancelled jobs may require rerun or queue investigation rather than code changes. 4. **Fetch job logs** - For each failed job, download the job logs: - `GET /api/v1/repos///actions/jobs//logs` - On Gitea 1.21 web fallback, download logs by UI job index: - `GET ///actions/runs//jobs//logs` - Start with job index `0`; if multiple jobs exist, inspect the run page or downloaded logs to map the failing job. - Save large logs to a temporary file outside tracked source paths. - Extract the first actionable error block, surrounding command, job name, workflow name, run URL, branch, and SHA. - If logs are missing, report that explicitly instead of inventing causes. 5. **Classify the failure** - Code/test failure: failing assertion, compile error, lint error, type error - Environment failure: missing secret, runner image, dependency install, network, cache, permission, or service startup - Workflow failure: invalid YAML, unsupported syntax, wrong trigger, bad path, wrong branch/ref assumption - Infrastructure failure: offline runner, stuck queue, cancelled run, timeout 6. **Create a fix plan** - Summarize the failure evidence with exact job/run identifiers. - Propose the smallest code or workflow change that matches the evidence. - Include local verification commands and the remote recheck path. - Do not implement before the user approves the fix plan. 7. **Implement after approval** - Apply only the approved fix. - Run the local command that most closely reproduces the failed job. - If the failure is workflow-only, validate the workflow file syntax and any referenced paths or scripts. 8. **Recheck** - Tell the user what must be pushed or rerun in Gitea. - If permitted, use the Gitea API to inspect the rerun status. - Final output must distinguish local verification from remote CI status. ## Output Contract - `Target:` repo, branch/SHA, PR or run ID - `Failed CI:` workflow, job, status, run URL or API path - `Evidence:` concise log snippet and classification - `Plan:` proposed fix, local verification, remote recheck - `Changes:` files changed after approval - `Result:` local checks run and remaining remote status ## Success Criteria - Failure analysis is based on Gitea Actions run/job data or pasted logs - The fix plan names the exact workflow run or job it addresses - No code or workflow edits happen before plan approval - Verification distinguishes local commands from remote Gitea Actions results - Tokens and private log content are not echoed unnecessarily ## Failure Handling - If authentication fails, ask the user to authenticate `tea` or provide a token through the environment; do not request secrets in chat - If the Gitea version lacks Actions API endpoints, ask for the relevant log text or a browser-copied job log - If an external CI provider owns the failing check, report the external URL and stop at evidence collection - If the failure is infrastructure-only, recommend rerun/runner investigation instead of editing code