ADR-001: Actions Runs List — Switch Data Source from /actions/tasks to /actions/runs

Field	Value
ID	ADR-001
Status	PROPOSED
Deciders	Maintainers
Date	2025-07
Related Issue	#29 — Timestamp enrichment via event_store

---

Context

The proxy exposes GET /api/v1/repos/{owner}/{repo}/actions/runs as an enriched endpoint over Forgejo. Historically, Forgejo had no native /actions/runs endpoint, so the proxy synthesised run data by querying the lower-level /actions/tasks endpoint and grouping/enriching the results.

Forgejo 14.x introduced a native GET /api/v1/repos/{owner}/{repo}/actions/runs endpoint that returns first-class run data with exact timestamps.

This ADR evaluates whether the proxy should switch its internal data source from /actions/tasks to the new /actions/runs endpoint.

---

Domain Model Clarification

Understanding the difference between the two Forgejo primitives is essential before comparing the options.

ActionTask — /api/v1/repos/{owner}/{repo}/actions/tasks

A task is a single job execution attempt within a workflow run.

• Each workflow run consists of one or more jobs.
• Each job can have one or more attempts (retries), each of which is a separate task.
• Tasks represent individual job executions with their own step-level results.

Key fields:

Field	Description
id	Task-level identifier
run_id	Points to the parent run
run_number	Per-repository sequential run counter
name	Job name
status	Job status (string enum)
conclusion	Job conclusion
started_at	When this job started
completed_at	When this job completed

This is a lower-level primitive — it maps to individual job/attempt combinations within a run.

Endpoint (via proxy): https://forgejo-proxy.hochguertel.work/api/v1/repos/{owner}/{repo}/actions/tasks → forwarded to: https://pastoral-oyster.pikapod.net/api/v1/repos/{owner}/{repo}/actions/tasks

---

ActionRun — /api/v1/repos/{owner}/{repo}/actions/runs

A run is a complete workflow execution triggered by an event (push, PR, tag, etc.).

• Contains metadata about the entire workflow lifecycle.
• Holds created, started, stopped, and updated timestamps at the workflow level.

Key fields:

Field	Description
id	Global sequential run ID (across all repos)
index_in_repo	Per-repository sequential counter — equivalent to run_number
title	Workflow run title (usually the commit message subject)
commit_sha	Full commit SHA
trigger_user	User who triggered the run
status	Integer enum (see table below)
conclusion	Run conclusion
created	Exact creation timestamp
started	Exact start timestamp
stopped	Exact stop timestamp (null if still running)
updated	Exact last-update timestamp
duration	Total duration in seconds
workflow_id	Workflow filename (e.g. ci.yml)

Native field names use non-_at suffixes (created, started, stopped) — not created_at.

Endpoint (via proxy — currently intercepted): https://forgejo-proxy.hochguertel.work/api/v1/repos/{owner}/{repo}/actions/runs → native Forgejo: https://pastoral-oyster.pikapod.net/api/v1/repos/{owner}/{repo}/actions/runs

---

Summary of Difference

Key Distinction

Tasks = individual job execution units (job-level granularity)

Runs = complete workflow execution events (workflow-level granularity)

One Run has many Tasks — one per job, potentially more per retry.

---

Current State — Proxy Data Flow

The proxy’s GET /api/v1/repos/{owner}/{repo}/actions/runs currently works as follows:

1. Receives the client request at https://forgejo-proxy.hochguertel.work/api/v1/repos/{owner}/{repo}/actions/runs
2. Calls Forgejo’s /api/v1/repos/{owner}/{repo}/actions/tasks internally
3. Groups tasks by run_number to reconstruct logical runs
4. Queries event_store.db (SQLite) to enrich created_at and finished_at timestamps — because tasks do not carry reliable run-level timestamps
5. Builds the jobs[] array from the grouped task data
6. Returns a normalised response using snake_case *_at field names

flowchart TD
    Client[CLI / API Client] -->|GET /api/v1/repos/owner/repo/actions/runs| Proxy
    Proxy -->|GET /api/v1/repos/owner/repo/actions/tasks| Forgejo[Forgejo\nhttps://pastoral-oyster.pikapod.net]
    Proxy -->|SELECT first_seen_at, finished_at| EventStore[(SQLite\nevent_store.db)]
    Forgejo -->|tasks list| Proxy
    Proxy -->|GROUP BY run_number| Grouping[Task Grouping\nLogic]
    Grouping --> EventStore
    EventStore -->|approximate timestamps| Grouping
    Grouping -->|enriched response| Client

Current Proxy Response Model

For each run in the list response:

{
  "run_number": 79,
  "display_title": "feat: add feature",
  "head_sha": "abc123",
  "head_branch": "main",
  "status": "success",
  "conclusion": "success",
  "created_at": "2025-06-01T10:00:00Z",
  "updated_at": "2025-06-01T10:05:00Z",
  "run_started_at": "2025-06-01T10:00:30Z",
  "finished_at": "2025-06-01T10:05:00Z",
  "workflow_id": "ci.yml",
  "jobs": [
    { "name": "build", "status": "success" }
  ]
}

Timestamp Accuracy

• created_at — from event_store (first time proxy observed the run) — APPROXIMATE
• updated_at — from event_store — APPROXIMATE
• finished_at — from event_store (first terminal-state observation) — APPROXIMATE
• run_started_at — from tasks.started_at — more accurate, but still task-derived

---

Forgejo Native API — What Was Discovered

Forgejo 14.x now exposes a native GET /api/v1/repos/{owner}/{repo}/actions/runs endpoint.

Native Response Model

{
  "id": 839,
  "index_in_repo": 79,
  "title": "feat: add feature",
  "commit_sha": "abc123def456...",
  "prettyref": "refs/heads/main",
  "status": 3,
  "trigger_user": { "login": "alice", "id": 1 },
  "created": "2025-06-01T10:00:00Z",
  "started": "2025-06-01T10:00:30Z",
  "stopped": "2025-06-01T10:05:00Z",
  "updated": "2025-06-01T10:05:00Z",
  "duration": 270,
  "jobs": null,
  "workflow_id": "ci.yml"
}

Status Integer Enum

Value	Meaning
1	waiting
2	running
3	success
4	failure
5	cancelled
6	skipped

Field Comparison: Native vs Proxy

Field	Native Forgejo	Proxy (current)	Notes
Run identifier	id (global) + index_in_repo	run_number	index_in_repo = run_number
Created timestamp	created ✅ exact	created_at ⚠️ approximate	Key improvement
Started timestamp	started ✅ exact	run_started_at (task-derived)	Key improvement
Stopped/finished	stopped ✅ exact	finished_at ⚠️ approximate	Key improvement
Updated timestamp	updated ✅ exact	updated_at ⚠️ approximate	Key improvement
Jobs breakdown	❌ null in list	✅ jobs[]	Proxy adds unique value
Workflow filter	❌ not supported	✅ ?workflow_id=	Proxy adds unique value
Status type	Integer enum	String enum	Proxy normalises
Field naming	created, started, stopped	created_at, run_started_at, finished_at	Proxy normalises

Note

The native endpoint does not include jobs[] in the list response. The proxy’s jobs[] enrichment remains a unique value-add that cannot be replaced by simply proxying the native endpoint.

---

Decision

Switch the proxy list endpoint to use the native /actions/runs as its primary data source.

The proxy will:

1. Call Forgejo’s native https://pastoral-oyster.pikapod.net/api/v1/repos/{owner}/{repo}/actions/runs
2. Map native field names to the normalised snake_case *_at format consumers expect
3. Enrich each run with a jobs[] array by querying /actions/tasks grouped by run_number
4. Apply ?workflow_id= and ?status= filtering (translating string status to integer for the native call)
5. Remove the event_store dependency for timestamp data

What the Proxy Continues to Add

Feature	Proxy Contribution
jobs[] in list response	Forgejo native list does not include jobs
?workflow_id= filter	Not natively supported
?status= filter (string)	Native uses integer enum; proxy translates
Normalised field names	created_at, run_started_at, finished_at instead of created/stopped
Backwards-compatible API surface	Consumers need no changes

---

Proposed Data Flow

flowchart TD
    Client[CLI / API Client] -->|GET /api/v1/repos/owner/repo/actions/runs| Proxy
    Proxy -->|GET /api/v1/repos/owner/repo/actions/runs| ForgejoRuns[Forgejo Runs API\nhttps://pastoral-oyster.pikapod.net]
    Proxy -->|GET /api/v1/repos/owner/repo/actions/tasks| ForgejoTasks[Forgejo Tasks API\nhttps://pastoral-oyster.pikapod.net]
    ForgejoRuns -->|exact timestamps: created, started, stopped, updated| Proxy
    ForgejoTasks -->|jobs list, grouped by run_number| Proxy
    Proxy -->|enriched with jobs + normalised fields| Client

Impact on event_store.db

Simplification

The event_store.db SQLite database was introduced specifically to work around the absence of reliable run-level timestamps (see issue #29).

Once the proxy uses native /actions/runs as its primary source, the event_store dependency for timestamps can be removed entirely. The SQLite database may still serve other purposes but is no longer needed for timestamp enrichment.

---

Consequences

Positive

• Accurate timestamps — created, started, stopped, updated are exact Forgejo values, not proxy-observed approximations.
• Simpler code path — No more task grouping logic or event_store timestamp lookups.
• Better correctness — Historical runs fetched fresh will have accurate timing data.
• Reduced state — event_store.db no longer needed for runs list timestamps.

Negative / Trade-offs

• Two upstream calls instead of one — the proxy must call both /actions/runs and /actions/tasks to build the enriched response (unless jobs[] is made optional/lazy).
• Field mapping required — The proxy must translate Forgejo’s integer status enum and non-_at field names.
• Potential for partial failure — If /actions/tasks is unavailable, jobs[] cannot be populated.

Neutral

• The external API surface (what consumers call) remains unchanged.
• run_number maps directly to index_in_repo — no consumer-visible identifier change.

---

Alternatives Considered

Option A: Keep current approach (tasks + event_store)

Rejected. Timestamps remain approximate. The event_store adds operational complexity (SQLite file, persistence, state drift). Now that a native runs endpoint exists, the approximation is unnecessary.

Option B: Pass through native runs endpoint directly (no enrichment)

Rejected. Removes the jobs[] enrichment that consumers depend on, and changes the field names and status type in a breaking way.

Option C: Native runs as primary, tasks for jobs only (this ADR)

Accepted. Best balance of accuracy, simplicity, and backwards compatibility.

---

Related Issues

• Issue #29 — Timestamp enrichment via event_store — the problem this decision partially resolves
• Issue tracker: https://pastoral-oyster.pikapod.net/tools/th-forgejo-cli/issues

---

Status

Status: PROPOSED

This decision has not yet been implemented. Implementation is pending review and approval by maintainers.

Once accepted, a follow-up implementation PR will be linked here.