# Skill: Actions

View, trigger, monitor, and manage GitHub Actions workflow runs and jobs.

## Commands Reference

### List Workflow Runs

```bash
# Recent runs across all workflows
gh run list --limit 10 --json databaseId,name,status,conclusion,headBranch,createdAt,event

# Filter by workflow
gh run list --workflow build.yml --json databaseId,status,conclusion,headBranch --limit 10

# Filter by branch
gh run list --branch main --json databaseId,name,status,conclusion --limit 10

# Filter by status
gh run list --status failure --json databaseId,name,headBranch,createdAt --limit 10
gh run list --status in_progress --json databaseId,name,headBranch

# Filter by event
gh run list --event push --json databaseId,name,status --limit 10
gh run list --event pull_request --json databaseId,name,status --limit 10

# Filter by user
gh run list --user "username" --json databaseId,name,status --limit 10

# Combine filters
gh run list --workflow ci.yml --branch main --status failure --limit 5 --json databaseId,name,conclusion,createdAt
```

### View a Workflow Run

```bash
# View run details
gh run view <run-id> --json databaseId,name,status,conclusion,headBranch,event,jobs,createdAt,updatedAt

# View with job breakdown
gh run view <run-id> --json jobs --jq '.jobs[] | "\(.name): \(.status) (\(.conclusion // "running"))"'

# View specific job steps
gh run view <run-id> --json jobs --jq '.jobs[] | select(.name == "build") | .steps[] | "\(.name): \(.conclusion // .status)"'

# Check if run succeeded
gh run view <run-id> --json conclusion --jq '.conclusion'

# Get run URL
gh run view <run-id> --json url --jq '.url'
```

### View Run Logs

```bash
# View logs for a run (all jobs)
gh run view <run-id> --log

# View logs for a failed job only
gh run view <run-id> --log-failed

# Download logs to a file
gh run view <run-id> --log > run-logs.txt

# View logs for specific job
gh run view <run-id> --job <job-id> --log
```

### Trigger a Workflow (workflow_dispatch)

```bash
# Trigger a workflow on default branch
gh workflow run deploy.yml

# Trigger on a specific branch
gh workflow run deploy.yml --ref feature/new-deploy

# With input parameters
gh workflow run deploy.yml -f environment=staging -f version=1.2.3

# With JSON inputs
gh workflow run deploy.yml --json -f '{"environment":"production","dry_run":false}'

# In another repo
gh workflow run deploy.yml -R owner/repo -f environment=staging
```

### Re-run Workflows

```bash
# Re-run all jobs in a run
gh run rerun <run-id>

# Re-run only failed jobs
gh run rerun <run-id> --failed

# Re-run with debug logging enabled
gh run rerun <run-id> --debug
```

### Cancel a Run

```bash
gh run cancel <run-id>
```

### Watch a Run (wait for completion)

```bash
# Watch a run until it completes (blocks)
gh run watch <run-id>

# Watch with exit code reflecting run result
gh run watch <run-id> --exit-status

# Watch most recent run
gh run watch $(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')
```

### List Workflows

```bash
# List all workflows in the repo
gh workflow list --json id,name,state

# Include disabled workflows
gh workflow list --all --json id,name,state
```

### Enable / Disable Workflows

```bash
# Disable a workflow
gh workflow disable deploy.yml

# Enable a workflow
gh workflow enable deploy.yml
```

### View Workflow Definition

```bash
# View workflow YAML
gh workflow view deploy.yml --yaml

# View workflow info
gh workflow view deploy.yml --json id,name,state
```

### Download Artifacts

```bash
# List artifacts for a run
gh run view <run-id> --json artifacts --jq '.artifacts[] | "\(.name) (\(.sizeInBytes) bytes)"'

# Download all artifacts from a run
gh run download <run-id>

# Download specific artifact by name
gh run download <run-id> --name "build-output"

# Download to a specific directory
gh run download <run-id> --name "test-results" --dir ./artifacts

# Download artifact matching a pattern
gh run download <run-id> --pattern "coverage-*"
```

### Manage Caches

```bash
# List caches
gh cache list --json id,key,size,createdAt --limit 20

# List caches sorted by size
gh cache list --json key,size --jq 'sort_by(.size) | reverse | .[] | "\(.key): \(.size)"' --limit 20

# Delete a specific cache
gh cache delete <cache-id>

# Delete caches by key prefix
gh cache list --json id,key --jq '.[] | select(.key | startswith("npm-")) | .id' | while read -r id; do
  gh cache delete "$id"
done
```

## Workflows

### CI Status Check

Quickly check if CI is passing for the current branch:

```bash
# Get status of latest run on current branch
BRANCH=$(git branch --show-current)
gh run list --branch "$BRANCH" --limit 1 --json databaseId,status,conclusion,name --jq '.[0] | "\(.name): \(.conclusion // .status)"'

# Or use pr checks if there's an open PR
gh pr checks
```

### Debug a Failed Run

```bash
# 1. Find the failed run
gh run list --status failure --limit 5 --json databaseId,name,headBranch,createdAt

# 2. View which jobs failed
gh run view <run-id> --json jobs --jq '.jobs[] | select(.conclusion == "failure") | "\(.name) (step: \(.steps[] | select(.conclusion == "failure") | .name))"'

# 3. Get the logs for failed jobs
gh run view <run-id> --log-failed

# 4. Re-run failed jobs with debug
gh run rerun <run-id> --failed --debug

# 5. Watch the re-run
gh run watch <run-id> --exit-status
```

### Deployment Workflow

```bash
# 1. Trigger deployment
gh workflow run deploy.yml -f environment=staging -f version=$(git describe --tags --abbrev=0)

# 2. Find the triggered run (most recent for that workflow)
sleep 5  # give GitHub a moment to register the run
RUN_ID=$(gh run list --workflow deploy.yml --limit 1 --json databaseId --jq '.[0].databaseId')

# 3. Watch it
gh run watch "$RUN_ID" --exit-status
echo "Deploy finished with exit code: $?"
```

### Monitor Multiple Workflows

```bash
# Dashboard view: status of all active runs
gh run list --status in_progress --json name,headBranch,status,createdAt --jq '.[] | "\(.name) on \(.headBranch) - started \(.createdAt)"'

# Latest run per workflow
for wf in $(gh workflow list --json name --jq '.[].name'); do
  LATEST=$(gh run list --workflow "$wf" --limit 1 --json conclusion,headBranch --jq '.[0] | "\(.conclusion // "running") (\(.headBranch))"' 2>/dev/null)
  echo "$wf: $LATEST"
done
```

### Cleanup Old Artifacts

```bash
# Delete artifacts older than 30 days (via API)
gh api repos/owner/repo/actions/artifacts --paginate --jq '.artifacts[] | select(.expired == false) | "\(.id) \(.name) \(.created_at)"' | while read -r id name date; do
  if [[ "$(date -d "$date" +%s)" -lt "$(date -d '30 days ago' +%s)" ]]; then
    gh api repos/owner/repo/actions/artifacts/"$id" -X DELETE
    echo "Deleted: $name ($id)"
  fi
done
```

### Wait for CI Before Merging

```bash
# Watch current PR's checks and merge when green
PR_NUMBER=$(gh pr view --json number --jq '.number')
gh pr checks "$PR_NUMBER" --watch --fail-fast
if [ $? -eq 0 ]; then
  gh pr merge "$PR_NUMBER" --squash --delete-branch
else
  echo "CI failed — not merging"
fi
```

## GitHub Actions API (Advanced)

For operations not covered by built-in commands:

```bash
# List workflow runs with more filters
gh api repos/owner/repo/actions/runs \
  --jq '.workflow_runs[] | select(.conclusion == "failure") | "\(.id): \(.name) (\(.head_branch))"'

# Get billing/usage info
gh api repos/owner/repo/actions/workflows --jq '.workflows[] | "\(.name): \(.state)"'

# Delete a workflow run
gh api repos/owner/repo/actions/runs/<run-id> -X DELETE

# List runner groups (org)
gh api orgs/my-org/actions/runner-groups --jq '.runner_groups[].name'

# List self-hosted runners
gh api repos/owner/repo/actions/runners --jq '.runners[] | "\(.name): \(.status)"'

# Download workflow run logs (zip)
gh api repos/owner/repo/actions/runs/<run-id>/logs > logs.zip

# Re-run with specific options
gh api repos/owner/repo/actions/runs/<run-id>/rerun -X POST -F enable_debug_logging=true
```

## Available JSON Fields

### Run fields (`gh run list` / `gh run view --json`):

`attempt`, `conclusion`, `createdAt`, `databaseId`, `displayTitle`, `event`, `headBranch`, `headSha`, `jobs`, `name`, `number`, `startedAt`, `status`, `updatedAt`, `url`, `workflowDatabaseId`, `workflowName`

### Job fields (nested in `jobs`):

`completedAt`, `conclusion`, `databaseId`, `name`, `startedAt`, `status`, `steps`, `url`

### Step fields (nested in `steps`):

`conclusion`, `name`, `number`, `status`

### Workflow fields (`gh workflow list --json`):

`id`, `name`, `path`, `state`

## Status and Conclusion Values

**Status** (run/job is in progress): `queued`, `in_progress`, `waiting`, `requested`, `pending`

**Conclusion** (run/job completed): `success`, `failure`, `cancelled`, `skipped`, `timed_out`, `action_required`, `neutral`, `stale`

## Tips

- Use `gh run watch --exit-status` in scripts — it exits non-zero if the run fails, making it composable with `&&`.
- `gh run view <id> --log-failed` is the fastest way to debug — it shows only the failed job's output.
- `gh workflow run` requires the workflow to have `workflow_dispatch` trigger defined.
- `gh run rerun --failed` only re-runs failed jobs, saving time and compute.
- `--debug` on rerun enables step debug logging (`ACTIONS_STEP_DEBUG`), giving much more verbose output.
- Use `gh cache list` to audit cache usage — large/stale caches slow down CI.
- For cross-repo workflow triggers, ensure your token has the `workflow` scope: `gh auth refresh -s workflow`.
- `gh pr checks` is a convenient shorthand when you just want to see CI status for the current PR.