orbreg

Documentation

Overview

Package orbreg asks the CircleCI orb registry what it knows about the orbs a .circleci/config.yml diff pins. There is no OSV.dev ecosystem and no deps.dev system for orbs, so — like Packagist, hex.pm, pub.dev, CRAN, Hackage, the Bazel Central Registry, Helm chart repositories and Ansible Galaxy before it — this package IS the metadata layer, not a fallback:

• Release ages and the ⏱ cooldown flag, from each orb version's createdAt in the registry's own GraphQL API (the endpoint the CircleCI CLI's `orb info` resolves against, queried anonymously for public orbs).
• Floating pins resolve to the release they fetch today: `volatile` → the newest published version, `5` / `5.1` → the newest matching version, rendered like an Actions floating major ("5 (=5.3.2)").
• Registry-verified unlisted detection: published orb versions are immutable — deleting one is a CircleCI-support action reserved for security problems — so an exact version the full version list omits, while the orb itself IS listed, is what a pulled release looks like. Absence is re-proven with an uncached fetch before it is claimed.
• The upstream source repository from the orb's display metadata (display.source_url in the published orb source), feeding verified compare links and -changelogs.

An orb the registry answers null for makes NO claims: unlisted orbs, private Server-install namespaces and typos all look the same from outside, and silence is the honest read.

circleci.com sends no CORS wildcard, so the browser (wasm) playground disables this layer; the CLI covers it fully.

Index

• Variables
• func Annotate(diffs []diffx.FileDiff, freshDays int) (bool, error)
• func Latest(name string) (string, error)

Variables

var BaseURL = "https://circleci.com/graphql-unstable"

BaseURL is the registry GraphQL endpoint; a var so tests can fake it.

var Enabled = true

Enabled gates the whole layer (the wasm playground turns it off: circleci.com sends no CORS wildcard).

var Now = time.Now

Now is a var so tests can pin the clock.

Functions

func Annotate

func Annotate(diffs []diffx.FileDiff, freshDays int) (bool, error)

Annotate fills orb-registry metadata on the diffs; see the package comment for what it covers. The returned bool reports whether at least one orb was actually vetted against the registry. freshDays mirrors -fresh-days. Best-effort: per-orb failures skip that orb; only total failure returns an error.

func Latest

func Latest(name string) (string, error)

Latest resolves the newest published version of an orb — what `volatile` would fetch (there are no pre-release orb versions; every published version is x.y.z).