---
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 <branch>`
     - `tea actions runs view <run-id>`
     - `tea actions runs logs <run-id> --job <job-id>`
     - `tea pulls view <pr>`
   - 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/<owner>/<repo>/actions/runs`
     - `GET /api/v1/repos/<owner>/<repo>/actions/runs/<run>`
     - `GET /api/v1/repos/<owner>/<repo>/actions/runs/<run>/jobs`
   - Web fallback for older Gitea:
     - `GET /<owner>/<repo>/actions`
     - Parse `/<owner>/<repo>/actions/runs/<run>` 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/<owner>/<repo>/actions/jobs/<job_id>/logs`
   - On Gitea 1.21 web fallback, download logs by UI job index:
     - `GET /<owner>/<repo>/actions/runs/<run>/jobs/<job-index>/logs`
     - First open the run page and read each job's status; take the index of a
       job whose status is `failure`, not index `0` by default. The failing job
       is rarely the first one, so a blind index `0` usually returns a passing
       job's log. Only fall back to scanning indices when the run page does not
       expose per-job status.
   - 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
