A Desk Light for GitLab Pipelines

The face of Status Light has three domed lenses: red at the top, amber in the middle and green below. GitLab pipeline events map neatly to them, although the product listing does not establish any USB, network or script control.

How do you get pipeline status out of GitLab?

GitLab documents pipeline webhooks that fire when a pipeline status changes. Their payload identifies the project, ref, commit, pipeline and detailed status. GitLab also exposes a Pipelines API that can list a project's pipelines and filter by branch, commit, source, scope or status.

Choose one path as authoritative. A webhook listener is event-driven, while a poller periodically reads current state. Combining both without a shared event identifier can make an older poll overwrite a newer delivery.

How does the webhook listener pattern work?

Subscribe the intended project to pipeline events and send them to a fast HTTPS receiver. Current GitLab guidance recommends signing tokens for new webhooks so the receiver can verify payload authenticity and integrity. It also provides a stable message identifier and timestamp that help reject replays and make retries idempotent.

Validate the signature before decoding trusted fields, check the pipeline-event header and accept only expected project and branch values. Respond promptly, then process the normalized event outside the request.

When is polling the better choice?

Polling is simpler when a desk machine cannot receive inbound HTTPS. Request the newest relevant pipeline from the API with a narrowly scoped credential, remember its identifier and update time, and sleep between checks. Use backoff for rate limits and service errors.

Polling trades immediacy for a smaller exposed surface. Set a stale threshold and preserve unknown when reads fail. Never let absence of a response become green.

How do you handle multiple projects on one light?

Maintain one state record per approved project and branch, then apply a priority rule. A confirmed failure outranks running work, and running work outranks completed success. Expire records that have not been refreshed and keep a terminal list showing which pipeline produced the aggregate.

The Status Light can represent the resulting three-state summary only if its actual control mechanism is confirmed. Test the software using captured payloads for running, success, failure, cancellation and unknown before writing a hardware adapter. Keep the project identifier and accepted refs in configuration rather than taking them from an untrusted event. Record the pipeline URL and commit so the aggregate can be investigated. Revoke the credential and signing material as part of removing the integration. Test a duplicate delivery and an out-of-order older status before relying on it.