diff --git a/.claude/skills/actions-runs/SKILL.md b/.claude/skills/actions-runs/SKILL.md new file mode 100644 index 0000000..4ad4ec5 --- /dev/null +++ b/.claude/skills/actions-runs/SKILL.md @@ -0,0 +1,195 @@ +--- +name: actions-runs +description: Fetch and monitor Gitea Actions CI results for a PR or branch +dependencies: tea +--- + +# Gitea Actions Run Monitoring + +Guide for inspecting CI workflow runs using the `tea actions runs` CLI. + +## Table of Contents + +- [Listing Runs](#listing-runs) +- [Viewing a Run](#viewing-a-run) +- [Viewing Logs](#viewing-logs) +- [Managing Workflows](#managing-workflows) +- [Common Workflows](#common-workflows) + +## Listing Runs + +```bash +# List recent runs (default: last 30) +tea actions runs ls --repo thatguygriff/walkies + +# Filter by branch (use this to find runs for a PR's branch) +tea actions runs ls --branch feature/my-branch --repo thatguygriff/walkies + +# Filter by status +tea actions runs ls --status failure --repo thatguygriff/walkies +tea actions runs ls --status success --repo thatguygriff/walkies +tea actions runs ls --status in_progress --repo thatguygriff/walkies +# Valid statuses: success, failure, pending, queued, in_progress, skipped, canceled + +# Filter by trigger event +tea actions runs ls --event pull_request --repo thatguygriff/walkies +tea actions runs ls --event push --repo thatguygriff/walkies + +# Filter by who triggered the run +tea actions runs ls --actor thatguygriff --repo thatguygriff/walkies + +# Filter by time range +tea actions runs ls --since 24h --repo thatguygriff/walkies +tea actions runs ls --since 2026-04-01 --until 2026-04-08 --repo thatguygriff/walkies + +# Increase result limit +tea actions runs ls --limit 50 --repo thatguygriff/walkies + +# JSON output for scripting +tea actions runs ls --output json --repo thatguygriff/walkies +``` + +## Viewing a Run + +Get the run ID from `tea actions runs ls`, then: + +```bash +# View run summary +tea actions runs view 42 --repo thatguygriff/walkies + +# View with jobs table (shows individual job statuses) +tea actions runs view 42 --jobs --repo thatguygriff/walkies + +# JSON output (includes job IDs for log fetching) +tea actions runs view 42 --output json --repo thatguygriff/walkies +``` + +## Viewing Logs + +```bash +# View logs for all jobs in a run +tea actions runs logs 42 --repo thatguygriff/walkies + +# View logs for a specific job +tea actions runs logs 42 --job JOB_ID --repo thatguygriff/walkies + +# Follow live logs for an in-progress job (requires --job) +tea actions runs logs 42 --job JOB_ID --follow --repo thatguygriff/walkies +``` + +Get job IDs from `tea actions runs view 42 --output json`. + +## Managing Workflows + +```bash +# List all workflow definitions in the repo +tea actions workflows ls --repo thatguygriff/walkies + +# Cancel or delete a run +tea actions runs delete 42 --repo thatguygriff/walkies +``` + +## Common Workflows + +### Check CI status for the current PR branch + +```bash +BRANCH=$(git branch --show-current) + +# Find the latest run for this branch +tea actions runs ls --branch "$BRANCH" --limit 5 --repo thatguygriff/walkies + +# Get the most recent run ID as JSON +RUN_ID=$(tea actions runs ls --branch "$BRANCH" --limit 1 --output json --repo thatguygriff/walkies \ + | jq -r '.[0].id') + +echo "Latest run: $RUN_ID" + +# View job-level summary +tea actions runs view "$RUN_ID" --jobs --repo thatguygriff/walkies +``` + +### Wait for CI to finish, then report status + +```bash +BRANCH=$(git branch --show-current) + +while true; do + STATUS=$(tea actions runs ls --branch "$BRANCH" --limit 1 --output json --repo thatguygriff/walkies \ + | jq -r '.[0].status') + echo "Status: $STATUS" + case "$STATUS" in + success|failure|canceled|skipped) break ;; + *) sleep 15 ;; + esac +done + +echo "Final CI status: $STATUS" +``` + +### Fetch logs for a failing run + +```bash +BRANCH=$(git branch --show-current) + +RUN_ID=$(tea actions runs ls --branch "$BRANCH" --status failure --limit 1 --output json \ + --repo thatguygriff/walkies | jq -r '.[0].id') + +# Show all logs for the failed run +tea actions runs logs "$RUN_ID" --repo thatguygriff/walkies + +# Or drill into a specific failing job +tea actions runs view "$RUN_ID" --output json --repo thatguygriff/walkies \ + | jq '.jobs[] | select(.status == "failure") | {id: .id, name: .name}' + +# Then fetch that job's logs +JOB_ID= +tea actions runs logs "$RUN_ID" --job "$JOB_ID" --repo thatguygriff/walkies +``` + +### Monitor a run that's currently in progress + +```bash +RUN_ID=42 + +# Get the in-progress job ID +JOB_ID=$(tea actions runs view "$RUN_ID" --output json --repo thatguygriff/walkies \ + | jq -r '.jobs[] | select(.status == "in_progress") | .id' | head -1) + +# Follow live logs +tea actions runs logs "$RUN_ID" --job "$JOB_ID" --follow --repo thatguygriff/walkies +``` + +## Quick Reference + +```bash +# List +tea actions runs ls # Last 30 runs +tea actions runs ls --branch feature/foo # Runs for a branch +tea actions runs ls --status failure # Failed runs only +tea actions runs ls --event pull_request # PR-triggered runs +tea actions runs ls --limit 1 --output json | jq '.[0]' # Latest run as JSON + +# View +tea actions runs view 42 # Run summary +tea actions runs view 42 --jobs # With jobs table +tea actions runs view 42 --output json # Full JSON (incl. job IDs) + +# Logs +tea actions runs logs 42 # All logs for a run +tea actions runs logs 42 --job JOB_ID # Specific job logs +tea actions runs logs 42 --job JOB_ID --follow # Follow live output + +# Cancel / delete +tea actions runs delete 42 # Cancel or delete run + +# Workflows +tea actions workflows ls # List workflow definitions +``` + +## Tips + +1. **Find the run for a PR**: PRs run on their head branch — filter with `--branch` using the feature branch name, not the PR number. +2. **Get job IDs**: Use `--output json` on `view` then `jq '.jobs[] | {id, name, status}'` to identify which job to drill into. +3. **Status polling**: The `--status in_progress` filter helps confirm a run is still going before following logs. +4. **Log noise**: Full run logs can be large — use `--job` to focus on the failing step.