---
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.