csh
/
playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
playbook/skills/gitea-fix-ci/SKILL.md

6.1 KiB
Raw Blame History

name description
gitea-fix-ci 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