# Workflow Runs and Tasks

## Endpoints

### List Workflow Runs

```
GET /repos/{owner}/{repo}/actions/runs
```

Query parameters:
- `page` (int) - Page number (1-based)
- `limit` (int) - Page size

Response contains a `workflow_runs` array.

```bash
# List workflow runs for a repository
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/runs?page=1&limit=10"
```

### Get Specific Run

```
GET /repos/{owner}/{repo}/actions/runs/{run_id}
```

```bash
# Get details of a specific workflow run
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}"
```

### List Tasks (Jobs)

```
GET /repos/{owner}/{repo}/actions/tasks
```

```bash
# List all tasks/jobs for a repository
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/tasks"
```

### List Runner Jobs

```
GET /repos/{owner}/{repo}/actions/runners/jobs
GET /orgs/{org}/actions/runners/jobs
GET /user/actions/runners/jobs
GET /admin/runners/jobs              # admin only
```

```bash
# List runner jobs at different scopes
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/runners/jobs"

curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/actions/runners/jobs"

curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/user/actions/runners/jobs"

# Admin only
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/admin/runners/jobs"
```

## Workflow Run Fields

| Field | Type | Description |
|-------|------|-------------|
| `id` | int | Unique run identifier |
| `status` | string | `waiting`, `running`, `success`, `failure`, `cancelled` |
| `conclusion` | string | Final result of the run |
| `event` | string | Trigger event: `push`, `pull_request`, `workflow_dispatch`, etc. |
| `head_sha` | string | Commit SHA that triggered the run |
| `head_branch` | string | Branch that triggered the run |
| `workflow_id` | int | ID of the workflow definition |
| `run_number` | int | Sequential run number for this workflow |
| `created_at` | string | ISO 8601 timestamp |
| `updated_at` | string | ISO 8601 timestamp |

## Getting CI Status for a PR

**Important**: To get CI status for a specific pull request, use commit statuses rather than trying to filter workflow runs. Workflow runs don't have a direct PR filter.

```bash
# Step 1: Get the PR's head SHA
HEAD_SHA=$(curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/pulls/{index}" | jq -r '.head.sha')

# Step 2: Get combined commit status for that SHA
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/commits/${HEAD_SHA}/status"

# Step 3: Or list individual statuses
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/commits/${HEAD_SHA}/statuses"
```

See [commit-statuses](../commit-statuses/README.md) for full details on commit status endpoints.

## Examples

```bash
# List the 5 most recent runs
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/runs?limit=5" | jq '.workflow_runs[] | {id, status, event, head_branch}'

# Get a specific run and check its status
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/runs/{run_id}" | jq '{id, status, conclusion, event}'

# List all tasks/jobs and filter by status
curl -s -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/actions/tasks" | jq '.task_runs[] | select(.status == "running")'
```
