149 lines
6.1 KiB
Markdown
149 lines
6.1 KiB
Markdown
---
|
|
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`
|
|
- 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
|