Skip to content
Custom Tools
fj-queue

fj-queue

1 min read
fj-queue terminal dashboard showing runner inventory, per-pod resource usage, per-repo backlog, and the waiting job queue
TL;DR. fj-queue is a small read-only tool that polls the Forgejo admin Actions API and shows, in one view, which runners are online, what’s running versus waiting, the per-repo backlog, and the FIFO-approximate queue order. Two faces from one aggregation layer: a live terminal dashboard for me, stable JSON for my agents. brew install fj-queue.

The problem

Forgejo’s web UI doesn’t aggregate Actions across repos. When CI feels backed up I want one screen that answers: are the runners online, how many jobs are running versus queued, which repo is hogging the queue, and is anything stuck because no runner matches its labels? tea and the raw API expose fragments; nothing stitches them together.

What it does

It hits the admin Actions API and renders runner inventory and state, running-versus-waiting totals, a FIFO-approximate queue order, per-repo backlog, and unschedulable-job warnings (a job whose runs_on no online runner can satisfy).

One aggregation layer, two output modes:

  • Humans: a live, in-place refreshing terminal dashboard (Rich).
  • Agents: a byte-deterministic JSON document (--format json) backed by a committed JSON Schema, so a script can branch on saturation, a repo’s queue position, or a blocked_reason.

It is strictly read-only. No cancel, rerun, or delete, so it’s safe to point at a busy production instance.

Install 

brew tap vtmocanu/tap
brew install fj-queue
fj-queue --host git.example.com

Needs an admin-scoped API token via --token or $FORGEJO_TOKEN.

Source, docs, and the JSON schema live in the repo: github.com/vtmocanu/fj-queue.

Last updated on
Tags: forgejo ci-cd custom-tools

More from Custom Tools

kcl-ci: DRY Forgejo Workflows in KCL (and Why I'm Sunsetting It) How I built a 3-layer KCL template library to keep ~30 repos' worth of Forgejo workflows DRY, what it taught me, and why Forgejo v15's reusable-workflow expansion is making me retire it. k8s-provision-tui: the DR automation I didn't know I was building A Textual TUI that drives the blue/green Kubernetes cutover end-to-end: live dashboard, menu-driven actions, and the realization that I was actually building disaster recovery automation. Prepuller Action: GitOps-native Image Caching, as Code A Forgejo Action for Flux-based GitOps repos that generates DaemonSets to pre-pull container images for labeled HelmReleases, keeping critical images warm on every worker node.