.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=<id from above>
+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.