A Desk Light for GitHub Actions

The matte-black Status Light presents three domed lenses in red, amber and green. GitHub Actions exposes enough run data to define those colours, but the light's listing does not confirm an automation interface, so a verified adapter is still required.

How do you get run status out of GitHub Actions?

A repository or GitHub App webhook can subscribe to workflow-run activity, and the completed action reports a finished run whether it succeeded or failed. For a desk that cannot safely receive web traffic, the official GitHub CLI can list runs and return JSON fields including status, conclusion, branch, commit and update time.

Filter to the intended repository, workflow and branch. The newest run across an entire repository may belong to an unrelated experiment, so do not let recency alone choose the signal.

How does the webhook pattern work?

Create a small HTTPS endpoint, subscribe only to workflow-run events and verify every delivery signature with the configured secret before parsing it. Accept the delivery quickly, place a normalized event on a local queue and make repeated delivery identifiers harmless.

The listener then checks repository identity, workflow, branch, action and conclusion. It should reject unknown payload shapes and avoid exposing a service directly from a laptop without authentication, patching and normal network controls.

How does polling with the gh CLI compare?

Polling needs no inbound endpoint. A scheduled local script can call gh run list for one repository and workflow, request structured JSON, compare the run identifier with its last observation and update only when the value changes. Authentication should have the minimum practical access.

The tradeoff is delay and API traffic. Use a modest interval, exponential backoff on errors and a stale state when repeated requests fail. Never convert an authentication error into green.

How should run states map to light colours?

Amber can mean queued or in progress, green can mean a success conclusion and red can cover failure, cancellation or timeout when the team treats those as action items. Neutral and skipped deserve an explicit policy rather than being silently grouped with success.

The Status Light matches that three-state display physically, but verify how the real unit accepts commands before designing the listener around it. Keep the workflow URL and commit visible in a companion log because a colour cannot identify the failing job. Test success and failure with known disposable runs, then disconnect the network to verify the display becomes stale or unknown. Record the last accepted run identifier and delivery time locally. A restart should restore that record without replaying an obsolete failure as a new event.