fj-queue

A read-only Forgejo Actions runner and CI queue dashboard.

Polls the Forgejo admin Actions API and renders runner inventory, queue totals, per-repo backlog, a FIFO-approximate queue order, and unschedulable-job warnings. Designed for two audiences:

• Humans: a live, in-place refreshing terminal UI (Rich) so an operator can see at a glance whether CI is saturated.
• Agents: a stable, byte-deterministic JSON document (--format json) backed by a committed JSON Schema, so scripts can branch on global saturation, a repo's queue position, and structured blocked_reason / warnings fields.

Quick Start

Install with Homebrew:

brew tap vtmocanu/tap
brew install fj-queue

This pulls in uv and Python automatically. Then run:

# Single snapshot
fj-queue --host git.example.com

# Live dashboard (default at a TTY)
fj-queue --host git.example.com --mode watch

# Agent: JSON output piped to jq
fj-queue --host git.example.com --format json | jq '.totals'

Pass an admin-scoped Forgejo API token via --token or $FORGEJO_TOKEN. A non-admin token exits 3.

Prefer running from a checkout without installing (uv run fj_queue.py)? See Installation.

For persistent settings, create fj-queue.toml in the current directory (or ~/.config/fj-queue/config.toml):

host = "git.example.com"

# Metrics and NCPS are OFF by default.
# Uncomment and supply a Prometheus URL to enable them.
# [metrics]
# enabled = true
# url = "https://prometheus.example.com"
# namespace = "ci-runners"

See config.toml.example for the full format with all supported keys.

Documentation

Document	Contents
Installation	Requirements, uv, token setup
Configuration	Flags, env vars, config file, precedence, discovery
Usage	Formats, modes, filtering, exit codes, examples
JSON contract	Schema shape, ordering, stability guarantees
Metrics and NCPS	Per-pod CPU/memory and NCPS cache status (opt-in)
Caveats	FIFO approximation, blocked jobs, filter scope

See also: Homelab Adventures: fj-queue for the background and design notes.