Glossary¶
Terms that appear in Diatreme's inputs, outputs, logs and errors.
Action surface. action.yml plus scripts/*.sh: the composite action that
runs on your runner. One of Diatreme's two halves.
App installation token. A short-lived credential GitHub issues to a GitHub
App for one repository it's installed on. What /token returns, and what the
release then authenticates with. Starts with ghs_.
Auth mode. How the action gets a token. public-app (the default) exchanges
an OIDC token at the broker. github-token uses a token you supply.
private-app mints from your own App's ID and key.
Broker. The hosted GitHub App backend the action calls to exchange an OIDC token for an App installation token. Also called the token broker.
Broker surface. Diatreme's other half: the code behind the broker. The
production deployment is the Python/Lambda broker in broker/ running on AWS
Lambda. The TypeScript Cloudflare Worker in worker/ serves as the code of
record and rollback target, but is not currently serving any hostname.
Fallback broker. The secondary hostname the action retries when the primary is unreachable or returns 5xx. Never tried on 4xx, because a rejected token is an answer, not an outage.
Floating major tag. @v2. Force-updated to the newest stable release of
that major after every release. Convenient, and it moves under you.
JWKS. JSON Web Key Set: the public keys an issuer publishes so anyone can verify tokens it signed. The broker fetches GitHub's, caches it, and keeps a last-known-good snapshot.
kid. Key ID. The field in a token's header naming which key from the JWKS
signed it. kid_not_found means the broker's cached key set didn't contain it.
OIDC token. The short-lived JWT a GitHub Actions job can mint about itself,
carrying claims like repository, ref and sha. Requires id-token: write.
Proof of which repository is asking, and the input to /token.
Promotion. Retagging an already-built image as a release version instead of
rebuilding it. Two kinds. On an ordinary release Diatreme promotes the pr-<N>
image, verifies its provenance labels against the release commit first, and
rebuilds rather than promoting anything stale. With promote-from you name a
prerelease tag and that exact build becomes the stable version: the git tag
lands on the prerelease's commit and records where it came from, and a retag
that cannot be done fails the run instead of rebuilding. See
Promoting a release candidate to stable.
Merge-back. The pull request that merges a release branch into the main
line after a stable release from it, so its hotfixes reach every later
release. Diatreme opens it from a merge-back/release-X.Y.Z branch rather than
from the release branch, which therefore never receives commits from the main
line. See Releasing from release branches.
Provenance labels. Metadata stamped onto an image at CI build time recording which commit it came from. What makes promotion verifiable.
Reason. The coarse, non-sensitive string the broker returns alongside
error on a verification failure, naming which check failed. See
Errors.
Release line. A release branch named after a version (release/1.4.0)
and every version cut from it: candidates of 1.4.0 until it ships, then 1.4.1,
1.4.2 for its hotfixes. With release-branch-versioning: branch the line's
name is the version source, not a versioning backend.
SBOM. Software Bill of Materials. Diatreme produces one in CycloneDX format during image scanning and routes it to Dependency-Track.
Snapshot (JWKS). A copy of the last key set that successfully verified a token, kept so the broker can still verify when an issuer's key endpoint is unreachable. Refused once it's over 24 hours old.
Versioning backend. The tool that decides the next version number:
semantic-release-python, semantic-release-npm, gitversion or
release-please. Detected from repository markers when versioning-tool is
auto.