# Diatreme Every documentation page, concatenated. Canonical site: https://docs.magmamoose.com/diatreme/ --- # Using the action Source: docs/action.md URL: https://docs.magmamoose.com/diatreme/action/ This page is a task-oriented tour. The **exhaustive input/output tables** live in the [repository README](https://github.com/MagmaMoose/diatreme#readme), this page does not duplicate them so they cannot drift. ## Modes ```yaml # CI: build + push the image. pr- on a pull request, # -- on a push or a dispatch - uses: MagmaMoose/diatreme@v2 with: mode: ci # Release: version, release, promote (default mode) - uses: MagmaMoose/diatreme@v2 with: mode: release environment: prod # Enable native auto-merge on a specific PR - uses: MagmaMoose/diatreme@v2 with: mode: enable-auto-merge pr-number: ${{ github.event.pull_request.number }} # Cut release/1.4.0 from the commit the workflow runs on - uses: MagmaMoose/diatreme@v2 with: mode: cut-release-branch version-override: 1.4.0 ``` ## Versioning-tool detection `versioning-tool: auto` (the default) resolves the backend from repository markers under `working-directory`, so one shared release workflow can serve repos on different tools. Detection is two-tier: 1. **A tool's own release config wins**: `pyproject.toml` `[tool.semantic_release]`, `.releaserc*` / `release.config.*`, `GitVersion.yml`, `release-please-config.json` / `.release-please-manifest.json`. 2. **Falls back to ecosystem manifests**: `pyproject.toml`/`setup.py`, `package.json`, `*.csproj`/`*.sln`, with a fixed precedence (`semantic-release-python` → `semantic-release-npm` → `gitversion` → `release-please`). Conflicting tier-1 configs, or no markers at all, fail with an actionable error. Passing an explicit `versioning-tool` skips detection entirely. ## Docker build definition Diatreme detects **how** to build your image from what's in the repo. You don't choose a builder, you just have the files: 1. **Docker Bake file present** (`docker-bake.hcl`, or `docker-bake.json` when `bake_file` is left at its default) → builds with `docker buildx bake`. Reach for this when you want multi-target builds, tag templating, multi-arch defaults, or local↔CI build parity. 2. **No bake file, but a `dockerfile` present** → Diatreme builds it directly with `docker buildx build -f .`, honouring the same knobs it passes to bake: `platforms`, the computed `${registry}/${image_name}:${version}` tag(s) (plus `:latest` on stable releases), provenance labels, GitHub Actions cache, the `build-github-token` build secret, and `--push`. It also emits a workflow **warning** so the fallback is visible in the run summary. 3. **Neither** → no image is built; versioning-only runs are unaffected. So the simplest consumer (one `Dockerfile`, no bake file) just works, instead of failing with `open docker-bake.hcl: no such file or directory`. When no `image_name` is given on this path, the base name falls back to the repository's own name (lowercased). !!! note "Multi-arch on the Dockerfile path" A plain Dockerfile has nowhere to declare a default platform set, so with `platforms` empty the fallback builds for the builder's default (single) architecture. Set `platforms: linux/amd64,linux/arm64` to produce a multi-arch manifest, exactly as bake would. For anything past a single image, prefer a `docker-bake.hcl`. ## Building a branch without a pull request `mode: ci` runs on a push or a dispatch as well as on a pull request. Off a pull request there is no number for `pr-`, so the image is tagged after the branch, the commit and the commit's time, and the tag comes back as the `image-tag` output: ```yaml on: push: branches: [test] jobs: build: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: MagmaMoose/diatreme@v2 id: ci with: mode: ci - run: echo "Built ${{ steps.ci.outputs.image-tag }}" # test-1a2b3c4-1760000000 ``` - **One tag per commit.** A deploy that moves to it rolls out, and the tag says which commit is running. A re-run of the same commit pushes the same tag. - **Sortable.** The last field is the commit time in unix seconds, so image automation can pick a branch's newest build. With Flux: `filterTags: {pattern: '^test-[a-f0-9]+-(?P[0-9]+)$', extract: '$ts'}` and `policy: {numerical: {order: asc}}`. - **For test environments, not releases.** `mode: release` promotes `pr-` images and rebuilds anything else, so a branch build never ships by itself. - The branch part is lowercased, `/` and anything else a tag cannot hold become `-`, and it is cut to fit Docker's 128 characters: `feature/123-Search` becomes `feature-123-search-1a2b3c4-1760000000`. `version-override` still names the image when it is set, on any event. ## Preview environments for pull requests GitOps preview controllers render one deploy per pull request head commit: Flux Operator's `ResourceSetInputProvider` (type `GitHubPullRequest`) exports a pull request's `id` and head `sha`, and Argo CD's pull request generator its `number` and `head_sha`. `pr-` is overwritten on every push, so a deploy pinned to it never rolls. Two opt-in inputs give those controllers a tag per commit and a way to wait for it: ```yaml on: pull_request: types: [opened, synchronize, reopened] # never labeled or unlabeled, see below jobs: ci: runs-on: ubuntu-latest permissions: contents: read packages: write pull-requests: write # image-building-label steps: - uses: MagmaMoose/diatreme@v2 id: ci with: mode: ci image-commit-tag: true image-building-label: deploy/preview-building - run: echo "Built ${{ steps.ci.outputs.image-commit-tag }}" # pr-12-1a2b3c4 ``` - **`image-commit-tag`** also pushes the pull request's image as `pr--`, the first seven characters of the pull request's **head** commit. Not `github.sha`: on a pull request that is the merge commit `actions/checkout` builds, which no controller knows. The tag goes out in the same push as `pr-`, so both name one image, and `mode: release` still promotes `pr-`. A pull request whose build is skipped (a deploy-only change, see [Deploying by pull request](#deploying-by-pull-request)) gets the tag by retagging its `pr-`. With no `pr-` yet there is no image to tag, and the run warns. - **`image-building-label`** is on the pull request while its images build. Diatreme adds it before the build and removes it once every tag, the commit tag included, is pushed. A run that fails or is cancelled leaves it on. Label changes use the token Diatreme already resolves (`github-token`, or the App token) and need `pull-requests: write`. A failed one only warns: a pull request from a fork gets a read-only `GITHUB_TOKEN`, so it builds without the label. The provider picks up pull requests labelled `deploy/preview`, and holds each one on its last exported commit while the building label is on: ```yaml apiVersion: fluxcd.controlplane.io/v1 kind: ResourceSetInputProvider metadata: name: app-pull-requests namespace: app-preview spec: type: GitHubPullRequest url: https://github.com/org/app secretRef: name: github-auth filter: labels: - deploy/preview skip: labels: - deploy/preview-building --- apiVersion: fluxcd.controlplane.io/v1 kind: ResourceSet metadata: name: app-previews namespace: app-preview spec: inputsFrom: - apiVersion: fluxcd.controlplane.io/v1 kind: ResourceSetInputProvider name: app-pull-requests resources: - apiVersion: apps/v1 kind: Deployment metadata: name: app-pr-<< inputs.id >> namespace: app-preview spec: selector: matchLabels: app: app-pr-<< inputs.id >> template: metadata: labels: app: app-pr-<< inputs.id >> spec: containers: - name: app image: ghcr.io/org/app:pr-<< inputs.id >>-<< inputs.sha | trunc 7 >> ``` After a push the provider sees the new head while the label is on, and keeps exporting the previous commit, so the preview stays on an image that exists. A pull request it has not exported yet waits for its first build. With Argo CD's pull request generator, the same tag is `pr-{{.number}}-{{.head_short_sha_7}}`. !!! warning "Keep `labeled` and `unlabeled` out of the ci trigger" A label changed with an App token starts workflows (one changed with `GITHUB_TOKEN` does not). A ci workflow that runs on `labeled` or `unlabeled` is then started again by Diatreme's own label change, one extra build each time. It cannot loop, because a run that the label started does not add it again. The default `pull_request` types are the right ones. ## Image scanning and SBOMs With `image-scan: 'true'`, Diatreme scans the assembled image with Trivy — the `pr-` candidate in `mode: ci`, and the promoted release tag in `mode: release`. **Only the released scan reports.** The security backends describe what is deployed, so they get one project version per release rather than one per pull request: - The released image's **CycloneDX SBOM** goes to **Dependency-Track**. - Optional released-image **findings** go to **DefectDojo**. The `pr-` scan feeds the gate and the log, and reports nowhere. Reporting is visibility-first: **non-blocking** unless you set `image-scan-gate` (which applies to `mode: ci` only — by release time the image has shipped), each sink is **failure-isolated** (a sink outage never fails your build), and a scanner that cannot run is a **build error**, not a silent pass. ## Signing images and provenance `image-sign: true` signs each released image with cosign in keyless mode and attaches SLSA build provenance, by digest, during `mode: release`. It's opt-in and off by default. ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release image-sign: true ``` The job needs `attestations: write` on top of its usual permissions, plus `id-token: write`, which `auth-mode: public-app` already requires. The number of images signed comes back in the `image-signed` output. Signing happens by digest rather than by tag, so a later retag can't change what was signed. ## Skipping images that are already published A multi-target promote that dies half way is the case that stings: the re-run redoes every target that already landed before it reaches the one that did not. `image-skip-existing` lets it resume instead. ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release image-skip-existing: true ``` **What it checks is identity, not existence.** A tag is a mutable pointer, and anyone holding `packages: write` on the registry can create one — so "a tag with that name is already there" is no evidence that Diatreme put it there. A gate that skipped on existence alone would let an image this pipeline never built be released, cosign-signed and attested under the release tag, and would step straight over the provenance check that exists to stop exactly that. So the gate runs *after* the provenance check on the promote source, and skips only when the release tag already resolves to the **same manifest digest** as the source it was about to retag. On a stable release it additionally requires `:latest` to resolve to that digest; if it does not — an interrupted promote that wrote the version tag but never moved `:latest` — the promote runs anyway and repairs it. Anything unproven (registry outage, expired credential, an unreadable manifest, a digest that differs) means promote it. Two limits worth knowing before you turn it on: - **It cannot skip a fresh build.** A rebuild's digest is not knowable in advance, so an image whose source failed provenance verification is rebuilt on every run. The saving is on the retag path. - **It does not defend against a compromised registry credential.** Nothing here does: image promotion already trusts whoever can write to your registry. The digest comparison keeps this gate from *widening* that trust, which is the reason it is a digest comparison and not a lookup. It applies to `mode: release` only — `pr-` is a mutable tag and CI must rebuild it on every push. Leave it off if you deliberately re-cut a version in place (a moved or force-pushed tag), because there the already-published tag is exactly what you meant to replace. `images-promoted`, `images-skipped` and `images-rebuilt` report what each run actually did. ## Promoting a prerelease to stable `promote-from` releases an existing prerelease as its stable version instead of cutting a new one. Give it the tag that was tested: ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release promote-from: v1.5.0-rc.3 # released as v1.5.0 ``` It is for flows where no branch builds a stable version: a release branch cuts `-rc.N` prereleases, one is signed off, and that build ships. Four things separate it from every other release path: - **You name the source.** No versioning tool runs and nothing is searched for. The version is the tag's own, minus its prerelease part. - **The stable tag lands on the prerelease's commit.** The run checks that commit out first, so it does not matter which branch the workflow was started on or how far it has moved since. - **It never rebuilds.** Each image is retagged from `:`. A source image the registry reports missing stops the run before the tag is pushed, and a retag that fails stops it too. A rebuild is not the build that was tested. For the same reason `publish-package` with `package-ecosystem: container`, which builds an image, is refused. - **`:latest` only moves forward.** It follows the promotion when the version is the highest stable one, and stays put when you promote a fix on an older release line. The target is always the last entry of `environments`, whatever `deployment-model` and `branch-map` say, so the production guardrails below apply. `version-override` and `force-bump` are rejected alongside it, and `version-file` is not written. The stable tag records the prerelease it came from, so re-running a promotion that died half way finishes it, and promoting anything else under a version that already exists is refused. Provenance is attested only when it would be true. `npm-provenance` and the SLSA attestation behind `image-sign` both name the commit the workflow was started on, so start the workflow from the prerelease tag if you use either. The full walkthrough, including a complete workflow and what each refusal means, is in [Promoting a release candidate to stable](how-to/promote-a-release-candidate.md). ## Release branches For a team that releases on a schedule: features merge into the main line, a release branch is cut when a release is due, its build goes to acceptance, and that same build is promoted to production. Hotfixes land on the release branch and are merged back. - `mode: cut-release-branch` creates `release/X.Y.Z` from the commit the workflow runs on, for the version in `version-override`, after checking the version is new. - `release-branch-versioning: branch` versions every run on a release branch from its name: `v1.4.0-rc.N` until 1.4.0 ships, then `v1.4.1-rc.1` for the first hotfix. No versioning tool runs, so commits need not be conventional. - `promote-from` releases a signed-off candidate as its stable version (above). - `release-branch-merge-back` opens the pull request that merges the release branch back after a stable release from it, from a `merge-back/` branch so the release branch itself is never updated from the main line. `release-branch-cleanup` deletes older release branches that are fully merged. The walkthrough, with the three workflows it takes, is [Releasing from release branches](how-to/release-from-release-branches.md). ## Deploying by pull request Diatreme releases; opening the pull requests that deploy a release to GitOps overlays is Tremvok's `gitops-pr` target. It starts from the GitHub Release Diatreme publishes (after the image is in the registry), opens a PR moving the image tag in the first overlay, and opens the next overlay's when that one merges. See [Tremvok's setup for `gitops-pr`](https://docs.magmamoose.com/tremvok/setup/#gitops-pr). Diatreme's part is `deploy-paths`, the directories those pull requests write: ```yaml on: push: branches: [master] # Merging a deploy PR is a deployment, not a release. paths-ignore: ['k8s/overlays/acc/**', 'k8s/overlays/prd/**'] pull_request: branches: [master] jobs: diatreme: steps: - uses: MagmaMoose/diatreme@v2 with: mode: ${{ github.event_name == 'pull_request' && 'ci' || 'release' }} deploy-paths: '["k8s/overlays/acc", "k8s/overlays/prd"]' ``` - **A deploy PR builds no image.** In `mode: ci`, a pull request that changes nothing outside `deploy-paths` skips the build and scan, and the `diatreme` check still reports, so a required-status rule is satisfied in seconds. - **A deploy merge is never released.** In `mode: release`, a push that changes nothing outside `deploy-paths` is refused before anything is tagged. Releasing it would publish a release, which opens a deploy PR for the new version, whose merge would be released in turn. The push trigger's `paths-ignore` is where that belongs; the refusal is for when it is missing. ## Branch naming `mode: ci` checks a pull request's branch name when `enforce_branch_naming` is on (the default). It accepts `/` for the built-in types (`feat`, `fix`, `chore`, `hotfix`, `release`, …), plus any you add in `extra-branch-prefixes`. A team with its own convention replaces the types with whole-name patterns: ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: ci branch-name-patterns: | feature/{issue}-{name} hotfix/{issue}-{name} ``` `{issue}` is a number, `{version}` is `major.minor.patch`, `{name}` is lowercase words joined by hyphens, `*` is one path segment and `**` is any depth. Everything else is literal and the whole name has to match. Bot branches and Diatreme's own (`promote/`, `merge-back/`) always pass. ## Who may cut a release By default, whoever can push to or merge into the release branch can cut a release. `allowed-release-actors` narrows that to a named list, and `allowed-release-actors-from` picks the environment it starts applying at — `@last`, the default, means production only. ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release allowed-release-actors: | alice @acme/release-managers acme-release-bot[bot] ``` Entries are GitHub logins, or teams written as `@org/team-slug` (`@team-slug` resolves against this repository's owner). Separate them with newlines or commas, or pass a JSON array. Matching is case-insensitive. Empty — the default — leaves releases unrestricted, so the gate stays inert until you populate it. Both the login the run is attributed to (`github.actor`) and the one that started it (`github.triggering_actor`) have to clear the list. They are the same person on an ordinary run; they differ on a **re-run**, where `github.actor` stays the original initiator. Checking only that would leave the gate open to a single click — anyone with write access could re-run an allowed person's failed release and cut production under their name, and the log would record a pass. This is not the gate `admin-required-from` provides. The two are independent, and both are enforced when both are set: | | `admin-required-from` | `allowed-release-actors` | | --- | --- | --- | | Fires on | `workflow_dispatch` only | every trigger, including push and merged promotion PRs | | Asks | is this person a repo admin? | is this principal on the list? | | Rights the release manager needs | repo admin: settings, secrets, branch protection | none | !!! warning "List every bot that merges on your behalf" The actor is whoever triggered the run, and for a promotion PR that merges itself that is the bot, not the person who approved it. A bot missing from the list turns every automated promotion into a failed release. Add its login (`acme-release-bot[bot]`, `dependabot[bot]`, …) next to the people. Team entries need the resolved token to be able to read org team membership; an allowlist of plain logins makes no API call at all. A membership lookup that cannot be completed **denies** the release — a check that did not happen is never read as approval. ## Issue references `issue-reference` makes `mode: ci` fail a pull request that does not reference an issue, so every change on the main line traces back to one: ```yaml on: pull_request: types: [opened, edited, synchronize, reopened] # edited: fixing the title re-runs it jobs: ci: runs-on: ubuntu-latest steps: - uses: MagmaMoose/diatreme@v2 with: mode: ci issue-reference: title ``` Check the part of the pull request that reaches the main line under the way you merge: | Value | Checks | For | | --- | --- | --- | | `title` | the pull request title | squash merges (the title becomes the commit subject) and merge commits (the title is in the commit body) | | `commits` | every non-merge commit (subject and body) | rebase merges, where each commit lands as it is | | `title, commits` | both | | A reference is anything GitHub links to an issue: `#4567`, `GH-4567`, `acme/app#4567` or an issue URL. A `#` right after a letter or digit (`C#12`) is not one. Bot branches, Diatreme's own branches and deploy-only pull requests (with `deploy-paths` set) are not checked. A failing commit check lists the commits to reword. ## Syncing the version into your manifests `version-file` writes the released version back into the files that carry it and commits them to the release branch. It takes one path, as it always has, or several separated by newlines (preferred) or commas — and each entry may be a glob: ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release version-file: | package.json packages/*/package.json version-file-json-path: .version ``` `*` and `**` are expanded against the workspace, and everything matched moves in a **single commit** rather than one commit per file. That is one commit, not an all-or-nothing guarantee, and the difference matters. A file that cannot be updated — a missing path, a glob that matched nothing, a path expression the file's shape rejects — is warned about and left out, and the files that *did* update are still committed. So a mistyped entry leaves that one manifest behind at the old version while its siblings move. Nothing fails; the only signal is a `::warning::` in the release log. **Read that log the first time you configure a multi-path `version-file`**, or check the resulting commit, rather than assuming a green release means every manifest moved. Format comes from the extension — `.yaml`/`.yml` through `yq` at `version-file-yaml-path` (default `.appVersion`, for Helm charts), everything else through `jq` at `version-file-json-path` — and that is one path expression per format for the whole list, so keep files that share a schema together. None of this can fail the release: the tag and the GitHub Release are already published by the time it runs. A path that does not exist, a glob that matches nothing, or a file the path expression cannot be applied to is warned about and skipped, and the remaining files still commit. `version-files-updated` reports how many were written. ## When the broker is down `auth-mode: public-app` calls a hosted broker for its token. A single hostname losing egress would block releases in every repository pinned to every published version, and no change shipped later can redirect those pins, so a second hostname travels with the action. | Input | Default | Behaviour | | --- | --- | --- | | `token-broker-url` | `https://api.diatreme.magmamoose.com` | Primary. Tried first, always. | | `token-broker-fallback-url` | `https://broker-diatreme.magmamoose.com` | Tried only when the primary is unreachable or answers 5xx. Set to an empty string to disable. | The fallback never fires on a 4xx. A rejected token is an answer, not an outage, and asking a second broker the same question would just get the same refusal more slowly. When the fallback is used, the run log carries a warning naming the primary's status, and the final error names which broker answered. Most repositories should leave both alone. Override them only if you run your own broker, and read [Security](security.md) first: pointing them elsewhere sends your OIDC tokens to that server. ## Publishing language packages `publish-package` can push to GitHub Packages or public registries, on github.com and GitHub Enterprise, for these ecosystems: `nuget`, `npm`, `maven`, `gradle`, `rubygems`, `container`, `helm`, `pip`, `s3`. See the README's "Publishing language packages" section for per-ecosystem inputs (feed URLs, trusted publishing, provenance). A public Helm chart has its own page: [Publishing a public Helm chart](how-to/publish-a-helm-chart.md). ## Outputs The action exposes: `version`, `tag`, `is-prerelease`, `released`, `prerelease-identifier`, `resolved-environment`, `package-published`, `image-scanned`, `image-findings`, `image-signed`, `resolved-image-name`, `images-promoted`, `images-skipped`, `images-rebuilt`, `version-files-updated`, `promoted-from`. The three `images-*` counters partition a `mode: release` promote: every image is either retagged from a verified source, skipped as already present, or rebuilt. On a `promote-from` run `images-rebuilt` is always 0. Each one's exact meaning is in the [README's output table](https://github.com/MagmaMoose/diatreme#outputs). --- # Architecture Source: docs/architecture.md URL: https://docs.magmamoose.com/diatreme/architecture/ Diatreme is two independent surfaces in one repo. They talk over HTTP and share no code. The action calls the broker's token endpoint; the broker never calls the action. ```mermaid flowchart LR subgraph runner["GitHub Actions runner"] A["action.yml
mode: ci / release / enable-auto-merge"] S["scripts/*.sh"] A --> S end subgraph broker["Hosted broker (Python/Lambda)"] T["POST /token
OIDC to App token"] end S -->|"HTTPS, sync"| T GH["GitHub REST + GraphQL"] T -->|"HTTPS, sync"| GH ``` The action calls the broker. The broker never calls the action. Every call is synchronous and the action fails hard on any fault, so a broker outage is a red X on the release rather than a silent skip. ## The composite action `action.yml` is deliberately thin glue (~108 inputs, ~63 steps); the real logic lives in `scripts/*.sh`, which are `bats`-tested. Three modes: - **`ci`**: build and push the `pr-` Docker image, optionally enforce branch naming, and (optionally) run a Trivy scan whose CycloneDX SBOM is routed to Dependency-Track and whose findings are routed to DefectDojo. Reporting is visibility-first: non-blocking unless `image-scan-gate`, sinks are failure-isolated, and a scanner that cannot run is a build error (not a finding). - **`release`**: resolve auth, determine the target environment, delegate versioning to the selected backend, normalize outputs, optionally promote the Docker image, publish a GitHub Release, and optionally open a promotion PR. Before promoting a `pr-` image it verifies the image's provenance labels (stamped by `mode: ci`) against the release commit's git tree; stale or unverifiable images are rebuilt from the release checkout instead of promoted. With `promote-from` it releases a named prerelease as its stable version instead: it checks out the prerelease's commit, confirms the source image exists before tagging, retags it, and never rebuilds. - **`enable-auto-merge`**: enable native GitHub auto-merge for a specific PR. **Versioning backends** are selected by `versioning-tool` (default `auto`, which detects from repository markers): `semantic-release-python`, `semantic-release-npm`, `gitversion`, `release-please`. ## The broker The broker is a GitHub App token minter: it exchanges an Actions OIDC token for a short-lived installation token, so callers don't have to register and run their own GitHub App. The production broker (`broker/app`) is a Python implementation running on AWS Lambda. The repository also contains `worker/src/index.ts`, a Cloudflare Worker that serves as the rollback target and code reference, but does not currently serve any hostname. !!! note "Production broker is Python/Lambda" `broker/app` runs on AWS Lambda behind API Gateway in eu-west-1, serving both broker hostnames. The TypeScript Cloudflare Worker (`worker/`) remains the code-of-record reference and rollback target. See [Deployment](operations/deployment.md). The production Python/Lambda broker serves one action-facing route: | Endpoint | Purpose | Auth | | --- | --- | --- | | `POST /token` | Exchange a GitHub Actions OIDC token for a short-lived App installation token. | OIDC (`id-token: write`) | The retired Cloudflare Worker (`worker/`) also implemented `POST /sign`, `GET /releases`, and `POST /webhook`; those routes are documented in [Broker API](reference/broker-api.md) but are not served by the production broker. OIDC verification pins the issuer before selecting its JWKS, so a forged `iss` can't select a foreign key. **GitHub Enterprise** (ghe.com / GHES) is opt-in via the `GHE_*` environment: a GHE token is verified against that tenant's issuer and minted via the GHE App against the GHE REST/GraphQL base. ### Failure modes at the boundary | Boundary | Fails how | Result | | --- | --- | --- | | Action to broker | Connection refused, DNS failure, or 5xx | The action retries once against the fallback hostname, then fails the step. A 4xx is never retried. | | Broker to issuer JWKS | Timeout, non-200, unparseable body | `503 oidc_key_fetch_failed`, unless a last-known-good snapshot under 24 hours old can rescue the request. | | Broker to GitHub REST | 404 on installation lookup | `404 app_not_installed`. Anything else unusable becomes a 500. | The full table is in [Errors](reference/errors.md). ## Deliberate tradeoffs **One hostname is a single point of failure, so the fallback ships inside the action.** A broker hostname losing egress would block releases in every repository pinned to every published version, and no change shipped later can redirect those pins. The secondary hostname travels with the action itself. **Frozen wire contract.** Consumers pin by SHA, so action input names, defaults and behaviour, and the broker's response bodies, are append-only. That constrains every change, and it's the price of being pinnable. **Fail hard, not soft.** A broker fault could be swallowed and the release allowed to continue unsigned or unversioned. Diatreme exits non-zero instead. A loud failure is cheaper than a wrong release. !!! note "Deeper map for contributors" `PROJECT_INDEX.json` at the repo root has the module and callgraph breakdown, and `AGENTS.md` has the repository boundary and editing rules. --- # Contributing Source: docs/contributing.md URL: https://docs.magmamoose.com/diatreme/contributing/ The authoritative contributor guide is [`AGENTS.md`](https://github.com/MagmaMoose/diatreme/blob/main/AGENTS.md) at the repo root. This page is a short orientation; `AGENTS.md` has the full rules. ## Repository boundary - Keep exactly **one** root action metadata file: `action.yml` (or `action.yaml`). CI fails otherwise. - The worker is **self-contained** under `worker/`; its only runtime dependency is `jose`. Do not couple it to the action scripts or vendor code from the private `MagmaMoose/diatreme-pro` dashboard repo. ## Editing rules - **Preserve action input names, output names, defaults, and behaviour** unless a breaking change is explicitly approved; every consumer pins to this contract. - Keep `README.md` examples aligned with `action.yml`. - Shell scripts must stay executable in Git (`git update-index --chmod=+x`). - Never commit secrets, `.dev.vars`, build output, or caches. ## Local validation Action surface (repo root): ```bash ruby -e 'require "yaml"; YAML.load_file("action.yml")' actionlint -color=false shellcheck -S warning scripts/*.sh bats tests/bats ``` Broker surface: - Python broker (`broker/`): ```bash pip install -r requirements-dev.txt && pytest tests ``` - TypeScript Worker rollback target (`cd worker/`): ```bash npm ci && npm run check # typecheck + vitest + wrangler dry-run ``` ## CI gates - `ci.yaml`: validates both surfaces (actionlint, shellcheck, bats, a python-semantic-release pin smoke-test; worker typecheck + tests; broker tests). - `release.yaml`: dogfoods `uses: ./` to release the action and moves the floating major tag. - `deploy-worker.yaml`: validates and deploys `worker/` to Cloudflare as the rollback target (not currently serving). - `security.yml`: the org Chargate security gate. - `docs.yml`: builds this site with `mkdocs build --strict` and publishes it to GitHub Pages on pushes to `main` touching `docs/**` or `mkdocs.yml`. - `broker-smoke-aws.yml`: weekly end-to-end proof that both broker hostnames (served by the Python/Lambda broker) turn a real OIDC token into a working installation token. Note that `docs.yml` only runs on `main`. A docs change that breaks a link passes pull-request CI and fails after merge, so run `mkdocs build --strict` locally before opening the PR. ## Where to put documentation Two surfaces, kept apart on purpose: - `./docs` is the published human site. Reference and architecture pages carry a `sources` HTML comment under the H1 listing the files they document, so staleness can be detected mechanically. Keep the nav in `mkdocs.yml` in sync with the pages. - `.claude/*.md` is terse agent context, not published. `README.md` owns the exhaustive input and output tables. Pages under `./docs` link to it rather than copying it, so the two can't drift. --- # Glossary Source: docs/glossary.md URL: https://docs.magmamoose.com/diatreme/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-` 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](how-to/promote-a-release-candidate.md). **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](how-to/release-from-release-branches.md). **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](reference/errors.md). **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`. --- # Promoting a release candidate to stable Source: docs/how-to/promote-a-release-candidate.md URL: https://docs.magmamoose.com/diatreme/how-to/promote-a-release-candidate/ Release the build that was tested, not a rebuild of it. `promote-from` takes a prerelease tag and releases that exact image as its stable version: `v1.5.0-rc.3` becomes `v1.5.0`, same commit, same image. ## When you need it Where a branch maps to production (`main: prod`), merging is the release and nothing on this page applies. It applies where **no branch ever builds a stable version**. A release branch cuts release candidates, QA signs one of them off, and that candidate is what ships: ```mermaid flowchart LR M[master] -->|push| D["v1.5.0-dev.N"] R["release/**"] -->|push| C["v1.5.0-rc.N"] C -->|QA| Q{signed off?} Q -->|"promote-from: v1.5.0-rc.3"| S["v1.5.0"] S --> A[acceptance] --> P[production] ``` Without `promote-from` the last arrow has no good answer. Under `deployment-model: bbd` a stable version only comes from a branch mapped to production, and it is built from a `pr-` image or rebuilt. Under `tbd` a later environment does retag, but it picks the newest prerelease rather than the one you name, tags whatever commit the workflow ran on, and rebuilds when the retag fails. ## The workflow The simplest setup adds one input to the release workflow you already have, so the promotion runs with exactly the registry, image and tag settings the prereleases were cut with: ```yaml name: Release on: push: branches: [master, 'release/**'] workflow_dispatch: inputs: promote-from: description: 'Prerelease to promote to stable, e.g. v1.5.0-rc.3. Empty for a normal release.' required: false type: string jobs: release: runs-on: ubuntu-latest permissions: contents: read packages: write id-token: write steps: - uses: MagmaMoose/diatreme@v2 with: deployment-model: bbd branch-map: '{"master": "dev", "release/*": "staging"}' environments: '["dev", "staging", "prod"]' prerelease-identifiers: '{"dev": "dev", "staging": "rc"}' promote-from: ${{ inputs.promote-from }} ``` Note what is missing from `branch-map`: an entry for `prod`. Nothing pushes its way to a stable version. The only route there is a dispatch with a tag in the box. On a push `inputs.promote-from` is empty and the run is an ordinary release. To promote, start the workflow by hand (from any branch) and enter the tag. A separate `promote.yml` works too. Give it the same `tag-prefix`, `registry`, image and auth inputs as the release workflow, or it will look for the image somewhere the prerelease never was. ## What a promotion does 1. **Resolves the tag.** It must exist, be a prerelease under `tag-prefix`, and carry the identifier of the environment before production (`rc` above). 2. **Checks out the prerelease's commit.** Everything after this reads that tree, whichever branch the workflow was started on. 3. **Applies the release guardrails.** A promotion is a production release, so `admin-required-from` and `allowed-release-actors` apply as usual. 4. **Asks the registry for the source image**, for every image the repository builds. An image the registry reports missing stops the run here, before anything is written. 5. **Pushes the stable tag** onto the prerelease's commit. Its message records where it came from: `Promoted-From: v1.5.0-rc.3`. 6. **Retags each image** from `:v1.5.0-rc.3` to `:v1.5.0`. 7. **Scans, signs and publishes** as any release does, when those are enabled. 8. **Publishes the GitHub Release**, with notes covering everything since the previous stable tag. `promoted-from` comes back as an output, and the job summary names the prerelease the release came from. ## What it will not do **Rebuild.** Every other retag in Diatreme falls back to a fresh build when it cannot be done. A promotion fails instead, because a fresh build under the stable tag is precisely the thing being ruled out. **Move a published version.** If `v1.5.0` already exists and is not this same promotion, the run stops. That covers a tag on a different commit, a tag an ordinary release cut, and a tag promoted from another prerelease that happens to sit on the same commit (`rc.4` after `rc.3` was promoted: same source, but a separate image). Cut `v1.5.1` instead. If the tag was a mistake, delete it and its GitHub Release, then promote again. **Drag `:latest` backwards.** `:latest` moves only when the promoted version is the highest stable version under `tag-prefix`. Promote a fix on an older release line (`v1.4.3` once `v1.5.0` is out) and `:latest` stays on `v1.5.0`. GitHub's own "Latest" marker follows the same rule. A package published by the same run does not: an npm package still takes the `latest` dist-tag, as it does on any stable release. **Build an image some other way.** `publish-package` with `package-ecosystem: container` runs `docker build` and pushes the result under the stable version, so it is refused on a promotion. Let Diatreme promote the image (a `docker-bake.hcl` or a `Dockerfile`) instead. Other ecosystems are unaffected: a NuGet or npm package is packed from the prerelease's commit with the stable version, which is the only way a version baked into a package can change. **Attest provenance to the wrong commit.** npm provenance and the SLSA attestation behind `image-sign` both record the commit the *workflow* was started on. Started from a branch that has moved on, that is not the commit the artifact was built from. So `npm-provenance` is refused unless the two are the same commit, and an image is signed but not attested (with a warning). To get both, start the workflow from the prerelease tag: pick `v1.5.0-rc.3` under "Use workflow from". **Write `version-file`.** The artifact is already built, and the run sits on a tag's commit rather than on a branch it could commit to. **Deploy.** Diatreme's job ends at the tag, the image and the GitHub Release. Rolling `v1.5.0` out to acceptance and then production is your deploy tooling's, typically triggered by the image tag or by `release: published`. ## When it stops Each of these fails the run before a tag, image or release is written. | Message | Cause | Fix | | --- | --- | --- | | `tag 'v1.5.0-rc.9' does not exist` | A mistyped tag. The message lists the prereleases of that version that do exist. | Use one of them. | | `is already a stable version` | A stable tag was passed. | Pass the prerelease. | | `is a 'dev' prerelease, but only 'rc' prereleases are promoted` | The tag is from an earlier channel than the one that feeds production. | Promote the `-rc.N` build. If `dev` really is the last stop before production, say so in `environments` and `prerelease-identifiers`. | | `v1.5.0 already exists on commit …` | A different build was already released as that version. | Cut a new version. | | `v1.5.0 was already promoted from v1.5.0-rc.3` | Another prerelease on the same commit was already promoted to that version. | Cut a new version. | | `was not cut by a promotion` | That version already exists on this commit, from an ordinary release. | Nothing to do: it is released. | | `cannot be combined with version-override` / `force-bump` | Two instructions for one version. | Remove the other input. | | `cannot be combined with publish-package and package-ecosystem: container` | That path builds a fresh image. | Promote the image through a bake file or `Dockerfile`, or turn `publish-package` off for the run. | | `npm-provenance would attest the package to commit …` | The workflow was started on a commit other than the prerelease's. | Start it from the prerelease tag, or turn `npm-provenance` off for the run. | | `a promotion always releases the stable version, to 'prod'` | `environment` names something other than the last entry of `environments`. | Remove `environment`. | | `environments is not a JSON array` / `prerelease-identifiers is not a JSON object` | A typo in one of the two inputs. | Fix the JSON. | | `source image(s) are not in the registry` | The prerelease has a git tag but no image: its build failed, or a retention policy removed it. | Cut a new prerelease and promote that one. | One failure comes later. If the registry cannot be asked about the source image (an outage, a credential it rejects), the run carries on rather than blocking on a guess, and the retag is what finds out: `could not retag as `, after the stable tag is pushed. Fix the cause and run the promotion again. ## Re-running A promotion is safe to run again. If a run dies after the stable tag is pushed (a registry outage during the retag, say), the next run finds `v1.5.0` already there, reads `Promoted-From: v1.5.0-rc.3` in it, and knows it is looking at its own unfinished work. It finishes what did not land. Steps that already landed change nothing: the image is retagged to the same source again, and an existing GitHub Release is left as it is. Set `image-skip-existing: true` and a resumed run also skips the images that already made it. If the source image is gone for good by then, there is nothing to resume with: delete the `v1.5.0` tag, cut a new prerelease, and promote that. ## Who may promote Started by hand, a promotion is a `workflow_dispatch` run targeting the last environment. By default that requires the actor to be a repository admin, and the auth token to read Repository: Administration. Two ways to change that: - `allowed-release-actors` names the people, teams and bots allowed to release, without handing them repository admin. - `admin-required-from: ''` turns the admin check off. See [Who may cut a release](../action.md#who-may-cut-a-release). ## Related - [Using the action](../action.md) - [Action reference](../reference/action.md) for `promote-from` in full. --- # Publishing a public Helm chart Source: docs/how-to/publish-a-helm-chart.md URL: https://docs.magmamoose.com/diatreme/how-to/publish-a-helm-chart/ `package-ecosystem: helm` packages a chart and pushes it to an OCI registry in the same run that tags the release and promotes its image, so the chart and the image it points at come from one commit. Four opt-in extras turn that into a chart strangers can find and trust: a lint gate, a cosign signature, Artifact Hub's repository metadata, and the Artifact Hub listing itself. ```yaml jobs: release: runs-on: ubuntu-latest permissions: contents: write id-token: write # the Diatreme App token, and keyless cosign packages: write # push the chart to GHCR steps: - uses: actions/checkout@v5 with: { fetch-depth: 0, fetch-tags: true } - uses: MagmaMoose/diatreme@v2 with: publish-package: 'true' package-ecosystem: helm package-path: charts/my-app helm-app-version: tag helm-lint: 'true' helm-sign: 'true' artifacthub-repo-file: artifacthub-repo.yml artifacthub-api-key-id: ${{ secrets.ARTIFACTHUB_API_KEY_ID }} artifacthub-api-key-secret: ${{ secrets.ARTIFACTHUB_API_KEY_SECRET }} ``` The chart lands at `oci://ghcr.io//charts/:`; `package-name` changes the `/charts` part. !!! warning "The default appVersion is not the image tag" The chart's `version` and `appVersion` are both the released version, `1.4.0`. Image promotion pushes the release **tag**, `v1.4.0` with the default `tag-prefix`. A chart that defaults its image tag to `.Chart.AppVersion`, which is the Helm convention, then points at a tag nobody pushed, and nothing fails until a pod cannot pull it. `helm-app-version: tag` sets appVersion to the tag instead. Use `helm-app-version: chart` for a chart that ships an image this repository does not build, to keep the appVersion committed in `Chart.yaml`. ## What each extra does | Input | Effect | | --- | --- | | `helm-lint` | `helm lint` before packaging. A failure publishes nothing. | | `helm-sign` | A keyless cosign signature on the pushed digest, which Artifact Hub shows as a signed chart. A re-run that finds the version already published signs the digest the registry holds, so a run that failed after pushing can be re-run into a signed chart. | | `artifacthub-repo-file` | Pushes `artifacthub-repo.yml` as the chart repository's `artifacthub.io` tag, which is where Artifact Hub looks for Verified Publisher and ownership claims. | | `artifacthub-api-key-id` + `-secret` | Lists the chart on Artifact Hub when it is not listed yet, and reports its repository ID in the `artifacthub-repository-id` output and the job summary. | Every extra is checked before anything is pushed, so a missing file, a lone API key or a name Artifact Hub would refuse fails the run with nothing published. ## A first public release, in order 1. **Make the package public.** A new GHCR package is private, and Artifact Hub reads charts anonymously: a private one is listed with nothing in it. The run warns when it cannot pull the chart anonymously. The switch is in the package's settings on GitHub, under Danger Zone. 2. **Create an Artifact Hub API key** (Control Panel, Settings, API keys) and store its ID and secret as repository or organization secrets. Set `artifacthub-org` to list the chart under an Artifact Hub organization rather than under the key's user. 3. **Release.** The job summary shows the new repository's ID. 4. **Commit `artifacthub-repo.yml`** with that ID. The next release pushes it, and Artifact Hub marks the publisher verified on its next scan: ```yaml repositoryID: 5f1e6a2b-0000-0000-0000-000000000000 owners: - name: Platform team email: platform@example.com ``` Artifact Hub lists one repository per OCI chart; it cannot list a whole registry. Its repository names are unique across Artifact Hub and appear in package URLs, so set `artifacthub-repository-name` when the chart's own name is taken. ## Annotations Artifact Hub reads `artifacthub.io/*` annotations from `Chart.yaml`: `license`, `links`, `maintainers`, `images` (the images its security report scans), `changes` and `prerelease`, among others. They ship inside the chart, so they are the chart's business, not the action's; Artifact Hub's control panel reports the ones it cannot parse. ## When something fails Artifact Hub is a sink. When it is down, or refuses the listing, the run warns and the release stands, because the chart is already published by then. Signing and the metadata push go to the same registry as the chart, so their failures fail the step; re-run the job, and the already-published chart is signed and described without being pushed again. --- # Releasing a versioned application suite Source: docs/how-to/release-a-versioned-suite.md URL: https://docs.magmamoose.com/diatreme/how-to/release-a-versioned-suite/ A suite repository can select the image versions of several applications without building those applications. Diatreme tags that selection, combines their published release notes, and publishes a suite GitHub Release with a `release.json` snapshot. Application Kubernetes resources can stay in their own repositories; Flux or another deployment system reads the central image selections. ## Central selections and application catalog Store one Kustomize selection per environment: ```yaml title="k8s/acc/kustomization.yaml" apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization resources: - ../../vendor/web/overlays/acc - ../../vendor/api/overlays/acc images: - name: ghcr.io/example/web newTag: v1.4.0 - name: ghcr.io/example/api newTag: v2.3.1 ``` The `vendor` directories in this example are supplied by the deployment system. Diatreme reads `images`; it does not fetch, build or deploy the resources. Each selection needs a unique `name` and a SemVer `newTag`; digest selections are rejected. Map those images to their application repositories: ```json title="suite/apps.json" { "apps": [ { "id": "web", "display_name": "Web application", "repository": "example/web", "image": "ghcr.io/example/web" }, { "id": "api", "display_name": "API service", "repository": "example/api", "image": "ghcr.io/example/api" } ] } ``` `id`, `repository` and `image` are required. `display_name` defaults to `id`. Every selected image must appear in the catalog. Duplicate IDs, duplicate images and malformed selections fail the run. ## Call the action with an explicit suite version Suite releases require `suite-manifest`, `suite-catalog`, `version-override`, `mode: release` and `detect-image-name: false`. Leave `image_name` empty. This path skips automatic version calculation and image builds or promotions. ```yaml name: Release suite on: workflow_dispatch: inputs: version: description: Suite version, for example 1.5.0-acc.2 required: true type: string permissions: contents: write concurrency: group: suite-release-${{ github.ref }} cancel-in-progress: false jobs: release: runs-on: ubuntu-latest steps: - uses: MagmaMoose/diatreme@v2 with: mode: release auth-mode: github-token github-token: ${{ secrets.SUITE_RELEASE_TOKEN }} deployment-model: tbd environment: acc environments: '["dev", "tst", "acc", "prd"]' prerelease-identifiers: '{"dev":"dev", "tst":"tst", "acc":"acc"}' suite-manifest: k8s/acc/kustomization.yaml suite-catalog: suite/apps.json version-override: ${{ inputs.version }} detect-image-name: 'false' ``` The action checks out the suite repository with complete history and tags. Pin the action to a published commit SHA in a production workflow. Use a token that can write the suite repository and read every catalog application repository, including its GitHub Releases. An installation token obtained from your own GitHub App works with `auth-mode: github-token`; the resulting changelog commit is attributed to that App. The default workflow `GITHUB_TOKEN` cannot read other private repositories. On GitHub Enterprise, the same token must cover the application repositories on that host; the action uses the workflow's `GITHUB_API_URL` and `GITHUB_SERVER_URL` for reads and links. ## The caller owns version planning The suite version is separate from each application's image version. Diatreme does not infer a suite bump from the application versions in this mode. For the environment configuration above, supply versions such as `1.5.0-dev.1`, `1.5.0-tst.3`, `1.5.0-acc.2` and stable `1.5.0` for `prd`. The environment order makes the final environment stable; the preceding ones are GitHub prereleases. The caller must choose the next base version and revision, skip unchanged selections, and serialize releases on the same branch. Omit `prd` from `prerelease-identifiers`. ## Aggregate notes and immutable snapshots Diatreme compares the selected manifest with the newest reachable suite tag for the same environment. An ACC release is compared with the preceding ACC release, even if a TST or production tag is newer. For each changed application, it reads every published release in the SemVer range `old < release <= new`, on the selected image's channel. Stable image upgrades include stable releases; candidate upgrades include that candidate channel. Draft releases are excluded. Initial suite selections and rollbacks include the selected application release only, with rollbacks labeled explicitly. The exact application release tag must match `newTag` and have published notes. Missing releases, empty notes and API failures stop the run before the suite tag is created. Notes are copied from the application releases, with links to those releases. Diatreme never edits the application repositories. After tagging, one GitHub-signed commit writes `CHANGELOG.md` and `suite/status.json` to the current suite branch. The commit preserves other environment entries and earlier changelog notes. It checks the branch head optimistically and refuses to write if the selected manifest has changed since the release checkout. The suite tag continues to identify the original selection commit; the later status commit does not move it. The GitHub Release contains the aggregate notes and an attached `release.json`. The snapshot includes the environment, suite tag, release URL and timestamp, selected image versions, previous suite tag, and changed applications with their version ranges and release notes. `suite/status.json` keeps the latest snapshot under each environment for dashboards and other readers. This records a release selection; deployment readiness comes from the deployment system. ## Resume a failed release Rerun the original workflow at the same commit with the same `version-override`. An existing suite tag at that commit resumes instead of creating another version. The status/changelog commit is idempotent, and an existing GitHub Release is left unchanged. A tag belonging to another commit, changed image selections for an already recorded tag, or an attempt to overwrite newer environment history fails. If the branch now contains a newer image selection, release that selection with a new suite version. Do not reuse an older suite tag for different images. --- # Releasing from release branches Source: docs/how-to/release-from-release-branches.md URL: https://docs.magmamoose.com/diatreme/how-to/release-from-release-branches/ For teams that release on a schedule rather than on every merge. Features reach the main line through pull requests. When a release is due, the team cuts a release branch named after the version it chose, the branch's build goes to acceptance, and once it is signed off that same build goes to production. A production bug is fixed on the release branch, shipped from it, and merged back into the main line. ```mermaid flowchart LR F["feature/123-search-filter"] -->|pull request| M[master] M -->|"cut-release-branch: 1.4.0"| R["release/1.4.0"] R -->|push| C["v1.4.0-rc.1"] --> A[acceptance] A -->|"promote-from: v1.4.0-rc.1"| S["v1.4.0"] --> P[production] H["hotfix/456-login-bug"] -->|pull request| R R -->|merge-back pull request| M ``` Four pieces of Diatreme carry it, each opt-in: | Piece | What it does | | --- | --- | | `mode: cut-release-branch` | Creates `release/X.Y.Z` from the commit the workflow runs on, after checking the version is new. | | `release-branch-versioning: branch` | Versions every run on a release branch from the branch name, with no versioning tool. | | `promote-from` | Releases a signed-off candidate as its stable version, retagging the tested image. | | `release-branch-merge-back`, `release-branch-cleanup` | After a stable release, open the pull request that merges the release branch back, and delete older release branches that are fully merged. | ## What decides the version The team does, when it cuts the branch. Nothing is computed from commit messages, so they do not have to follow Conventional Commits. | On `release/1.4.0` | Cut as | | --- | --- | | The branch is cut | `v1.4.0-rc.1` | | A fix lands before 1.4.0 ships | `v1.4.0-rc.2` | | `v1.4.0-rc.2` is promoted | `v1.4.0`, the same image | | A hotfix lands after 1.4.0 shipped | `v1.4.1-rc.1` | | A run is repeated on a commit that already holds its candidate | the same candidate, finished rather than cut again | | A run on a commit already released | nothing | The branch keeps its name for its whole life: `release/1.4.0` is the 1.4 line, and its hotfixes ship as 1.4.1, 1.4.2 and so on. A shipped version is never cut again, because it is a different build from the one now in production. ## The workflows Three small workflows. Each uses the default `auth-mode: public-app`, so each job needs `id-token: write` and the [Diatreme App](https://github.com/apps/diatreme/installations/new) installed. ### Pull requests Builds the `pr-` image a release later promotes, and holds branch names to the team's convention: ```yaml name: CI on: pull_request: branches: [master, 'release/**'] jobs: ci: runs-on: ubuntu-latest permissions: contents: read packages: write steps: - uses: MagmaMoose/diatreme@v2 with: mode: ci branch-name-patterns: | feature/{issue}-{name} hotfix/{issue}-{name} ``` `{issue}` is a number, `{name}` is lowercase words joined by hyphens, and the whole name has to match, so `feature/search-filter` and `feature/123_Search` are refused. Add `deploy/**` if a deploy tool opens pull requests from `deploy/` branches. Diatreme's own `merge-back/` branches always pass. ### Cut a release ```yaml name: Cut release on: workflow_dispatch: inputs: version: description: 'Version to release, e.g. 1.4.0' required: true jobs: cut: runs-on: ubuntu-latest permissions: contents: read id-token: write steps: - uses: MagmaMoose/diatreme@v2 with: mode: cut-release-branch version-override: ${{ inputs.version }} ``` Run it on `master`. It refuses a version that is already released, one that is not above the newest release, one with a prerelease part (`1.4.0-rc1`: the branch carries the release number only), and a `release/X.Y.Z` that already exists on another commit. Nothing else happens in this run. The new branch's push starts the release workflow below, which cuts the first candidate. A branch created with `GITHUB_TOKEN` starts no workflow, which is why this uses the App token. If the release workflow did not start (a `paths-ignore` on its push trigger can skip a new branch), run it by hand on the release branch. ### Release Cuts a candidate on every push to a release branch, and promotes one by hand: ```yaml name: Release on: push: branches: ['release/**'] workflow_dispatch: inputs: promote-from: description: 'Candidate to release to production, e.g. v1.4.0-rc.2. Empty cuts a candidate from the branch this runs on.' required: false concurrency: group: release-${{ github.ref }} cancel-in-progress: false jobs: release: runs-on: ubuntu-latest permissions: contents: read packages: write id-token: write steps: - uses: MagmaMoose/diatreme@v2 with: deployment-model: bbd branch-map: '{"release/*": "acc"}' environments: '["acc", "prd"]' prerelease-identifiers: '{"acc": "rc"}' release-branch-versioning: branch promote-from: ${{ inputs.promote-from }} release-branch-merge-back: '@default' release-branch-cleanup: true ``` - **`concurrency`** keeps two fixes merged in quick succession from racing for the same candidate number. A run that loses such a race anyway fails loudly instead of leaving its commit without a release. - **The build happens once.** A candidate's image is the merged pull request's `pr-` image when its provenance matches the release commit, otherwise a fresh build from the release branch. The promotion retags that image and never rebuilds; see [Promoting a release candidate](promote-a-release-candidate.md). - **Promoting is a production release**, so by default only repository admins may start it. To let named people or teams promote without admin rights, set `admin-required-from: ''` and list them in `allowed-release-actors`, which applies to every trigger. See [Who may cut a release](../action.md#who-may-cut-a-release). ## Hotfixes 1. Branch `hotfix/456-login-bug` from the release branch production runs, and open the pull request against that release branch. 2. Merging it cuts the next candidate (`v1.4.1-rc.1` once 1.4.0 shipped), which goes to acceptance. 3. Promote it: `promote-from: v1.4.1-rc.1`. 4. The promotion opens a pull request merging the release branch into `master`. Review it and merge it **with a merge commit**, so `master` carries the fix's own commits and every later release contains it. The merge-back pull request comes from `merge-back/release-1.4.0`, a branch that starts at the release branch's head. It never comes from the release branch itself: "Update branch" and conflict resolution on a pull request commit the target into its head branch, which would put unreleased work from `master` into the next hotfix. Resolve conflicts on the merge-back branch. A later fix released from the same line moves that branch forward and reuses the pull request. A release with no hotfix has nothing to merge back, and gets no pull request. ## Cleaning up, and patching an old line `release-branch-cleanup: true` deletes, after each stable release, the release branches of older lines whose head `master` already contains. Promoting 1.5.0 removes `release/1.4.0` once its hotfixes are merged back. A line with an unmerged fix is kept, with a notice naming it. What a deleted line shipped stays reachable through its tags. To patch it, run **Cut release** on the line's latest tag (**Use workflow from** → `v1.4.2`) with the line's version (`1.4.0`). That reopens `release/1.4.0` at the shipped commit, and the next fix merged into it is cut as `v1.4.3-rc.1`. ## Rules worth adding These belong to the repository, not to Diatreme, and make the flow hard to get wrong: - **`release/**`**: restrict branch creation to the Diatreme App, so a release branch only ever comes from **Cut release**; require pull requests; block force pushes. Let the App bypass deletion if you turn on cleanup. - **`master`**: require pull requests, and keep **Allow merge commits** on in the repository settings. The merge-back needs it. Diatreme warns, in the log and in the pull request, when it is off. ## What it will not do **Deploy.** Diatreme's job ends at the tag, the image and the GitHub Release. Deploy each candidate to acceptance and each promoted version to production with your deploy tooling, typically triggered by `release: published`. With [Tremvok](https://github.com/MagmaMoose/tremvok), `gitops-pr` opens those deploy pull requests. **Cherry-pick.** A fix reaches `master` through the merge-back pull request, never as a copy. **Merge the merge-back pull request.** A person reviews and merges it. **Version a branch without a version in its name.** `release/next` or `test` is left to the configured versioning tool, so a shared integration branch keeps working as it did. ## Related - [Promoting a release candidate](promote-a-release-candidate.md) - [Using the action](../action.md) - [Action reference](../reference/action.md) for every input named here. --- # Releasing several packages from one repository Source: docs/how-to/release-several-packages.md URL: https://docs.magmamoose.com/diatreme/how-to/release-several-packages/ One repository, several independently versioned packages. `tag-prefix` is what keeps their version histories apart. !!! danger "A wrong `tag-prefix` ships the wrong version, silently" Nothing errors. The release succeeds, the tag is created, the artifact publishes — it just carries a version computed from another package's history. This is the one setting on this page worth double-checking before a first release. Diatreme releases **one versioned unit per job**. To release more than one package out of a single repository, run one job per package, each pointed at that package's directory and its own tag series. The versioning tools do the path filtering; Diatreme's part is to keep every tag lookup scoped to the package being released. ## `tag-prefix` is what scopes the release Give each package a distinct tag series and tell Diatreme about it: ```yaml jobs: release-core: steps: - uses: actions/checkout@v5 with: { fetch-depth: 0, fetch-tags: true } - uses: MagmaMoose/diatreme@v2 with: working-directory: packages/core tag-prefix: 'core-v' # ← tags are core-v1.2.3 publish-package: 'true' package-ecosystem: pip package-path: packages/core ``` **This input is not cosmetic here.** Diatreme resolves "what was the last release?" from the repository's tags. Unscoped, that question is answered by whichever package released most recently — and the answer is a real version attached to a real tag, so nothing errors. The wrong number simply flows into the image tag, the published package and the GitHub Release. Every tag lookup in the action is scoped by `tag-prefix`; leave it at the default `v` in a multi-package repo and the packages will read each other's versions. `tag-prefix` must agree with the tag format the versioning tool writes. Diatreme cannot read that out of your tool's config, so the two are set independently and it is on you to keep them in step. ## Python — `python-semantic-release` PSR has had a monorepo commit parser since **v10.4.0**. Configure it in the package's own `pyproject.toml`; Diatreme runs PSR with `working-directory` as its cwd, so this is the file it reads: ```toml [tool.semantic_release] commit_parser = "conventional-monorepo" tag_format = "core-v{version}" # ← must match tag-prefix above [tool.semantic_release.commit_parser_options] path_filters = ["."] # only commits touching this directory scope_prefix = "core-" # optional: also match feat(core-api): ``` `path_filters` accepts negated patterns prefixed with `!`. ## Node — `semantic-release-monorepo` semantic-release has no built-in equivalent; the community shareable config does the filtering. Declare it in the package's `.releaserc.json`: ```json { "extends": "semantic-release-monorepo", "plugins": ["@semantic-release/commit-analyzer", "@semantic-release/github"] } ``` Diatreme installs whatever your config declares — including `extends`, which it must, because `semantic-release-monorepo` is only ever referenced there and never appears under `plugins`. A shareable config that is not installed fails at config load with `MODULE_NOT_FOUND`, before any release logic runs. ## Checkout depth Path filtering needs history, and comparing against the previous release needs tags. `fetch-depth: 0` and `fetch-tags: true` on the checkout are required — with a shallow clone the parsers see a truncated commit range and quietly under-report what changed. --- # Diatreme Source: docs/index.md URL: https://docs.magmamoose.com/diatreme/ **Diatreme is a release/deployment orchestrator.** It has two independent surfaces in one repository that communicate over HTTP, neither imports the other: - **Composite action** (`action.yml` + `scripts/`), published to the GitHub Marketplace. Runs semantic versioning, GitHub Releases, Docker image build and promotion, image scanning with SBOM/finding routing, and promotion-PR automation. - **Hosted broker**, the GitHub App backend at `api.diatreme.magmamoose.com`. An OIDC to installation-token minter: the action exchanges a GitHub Actions OIDC token here for a short-lived installation token. Most users never touch it directly. `broker/` is the Python/Lambda production implementation; `worker/` is the retired Cloudflare Worker kept as code-of-record. See [Deployment](operations/deployment.md) for what serves each hostname. Install the action: ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release ``` !!! tip "Where to go next" - New here? Start with **[Setup](setup.md)**. - Want the big picture? See **[Architecture](architecture.md)**. - Configuring a pipeline? See **[Using the action](action.md)**. - Hit a red X? Go straight to **[Errors](reference/errors.md)**. - Running your own broker? See **[Broker configuration](reference/configuration.md)**. - The full, exhaustive input/output reference lives in the [repository README](https://github.com/MagmaMoose/diatreme#readme). ## The two surfaces at a glance | Surface | Path | Toolchain | Ships to | | --- | --- | --- | --- | | Composite action | `action.yml` + `scripts/*.sh` | Bash, `actionlint`, `shellcheck`, `bats` | GitHub Marketplace | | Broker (production) | `broker/` | Python, `pytest`, `boto3` | AWS Lambda, eu-west-1 | | Broker (legacy) | `worker/` | TypeScript, `wrangler`, `vitest` | Rollback target (not currently serving) | ## Related - **[MagmaMoose/diatreme-pro](https://github.com/MagmaMoose/diatreme-pro)**: the separate private observability dashboard (release/run history) for the broker. --- # Deployment Source: docs/operations/deployment.md URL: https://docs.magmamoose.com/diatreme/operations/deployment/ Three things ship out of this repository on their own schedules: the composite action, the broker, and this site. ## What serves the broker today The two broker hostnames both answer from AWS Lambda behind API Gateway in `eu-west-1`. ```mermaid flowchart LR A["api.diatreme.magmamoose.com
(DNS only)"] -->|HTTPS| G["API Gateway
eu-west-1"] B["broker-diatreme.magmamoose.com
(proxied)"] -->|HTTPS| CF[Cloudflare proxy] CF -->|HTTPS| G G -->|invoke| L[Lambda broker] L -->|HTTPS| GH[api.github.com] L -->|HTTPS| J["token.actions.githubusercontent.com
JWKS"] ``` `api.diatreme.magmamoose.com` is the default `token-broker-url` frozen into every published version of the action, so it carries the consumer traffic. It resolves straight to the API Gateway custom domain with no proxy in front. `broker-diatreme.magmamoose.com` is the shipped fallback and reaches the same gateway through the Cloudflare proxy. Confirm which is which at any time: ```bash dig +short api.diatreme.magmamoose.com CNAME dig +short broker-diatreme.magmamoose.com ``` !!! warning "Editing `worker/` does not change production" Both broker hostnames answer from AWS Lambda running the Python broker implementation in `broker/`. The TypeScript Cloudflare Worker (`worker/`) remains in the repository as the rollback target, but it is not what consumers hit. See [Architecture](../architecture.md) for more. ### Rolling back to Cloudflare The Cloudflare Worker stays deployed and configured precisely so the hostnames can be pointed back at it. Rollback is a DNS change plus a Cloudflare route, not a redeploy. Verify with the smoke workflow below before and after. ## Deploying the broker (Cloudflare) `deploy-worker.yaml` runs on every push to `main` touching `worker/**` or the workflow itself. It installs, runs `npm run check` (typecheck, tests, and a wrangler dry run), injects the KV namespace IDs, then deploys. Required repository secrets: | Secret | Purpose | | --- | --- | | `CLOUDFLARE_API_TOKEN` | Wrangler auth. | | `CLOUDFLARE_ACCOUNT_ID` | Target account. | Optional repository variables: | Variable | Purpose | | --- | --- | | `DIATREME_JWKS_CACHE_ID` | KV namespace holding last-known-good JWKS snapshots. | | `COPILOT_QUOTA_KV_ID` | KV namespace caching the `/releases` aggregate. | The injection step is skipped when both are empty, and the deploy still succeeds. Namespace IDs are injected rather than committed so a self-hoster never inherits someone else's namespace. !!! warning "A deleted namespace fails the deploy, not the request" If one of those variables points at a namespace that no longer exists, every deploy fails at the wrangler step while the running broker keeps serving. The symptom is that merges stop reaching production with nothing obviously broken. Check the workflow's history, not the broker's logs. Deploy by hand from a working tree: ```bash cd worker npm ci npm run check wrangler deploy ``` Secrets are set once per environment and are not in the repository: ```bash wrangler secret put GITHUB_APP_ID wrangler secret put GITHUB_APP_PRIVATE_KEY wrangler secret put PROCESS_TRIGGER_SECRET ``` Every variable is described in [Configuration](../reference/configuration.md). ### Public entry points are off on purpose `workers_dev` and `preview_urls` are both `false` in `worker/wrangler.jsonc`. Each would be a publicly reachable door to a live token minter, inheriting production secrets and sitting outside whatever rules are bound to the custom domain. Leave them off. ## Verifying the broker end to end Synthetic probes prove routing and the error ladder, but they can only ever be rejected, so they can't prove the thing that matters: that a genuine Actions OIDC token comes back as a usable installation token. Only a real runner can mint one. `broker-smoke-aws.yml` does that. It runs Mondays at 06:00 UTC and on demand. For each hostname it mints a real OIDC token, exchanges it, then uses the returned token against the GitHub API and asserts it authenticates as the expected repository. Run it on demand: ```bash gh workflow run broker-smoke-aws.yml ``` A failure means an expired App key, a revoked installation, or an IAM, SSM or routing change. It costs one Lambda invocation and two API calls a week. ## Releasing the action `release.yaml` dogfoods the action against itself with `uses: ./`, then force-updates the floating major tag once semantic-release publishes a stable version. Consumers pin `@v2`, a full tag like `@v2.4.6`, or a SHA. Because consumers pin by SHA, action input names, defaults, behaviour, and the broker's wire responses are frozen. Changing one breaks repositories whose maintainers cannot be reached. Treat both as append-only. ## Publishing this site `docs.yml` builds with `mkdocs build --strict` and deploys to Cloudflare Workers on every push to `main` touching `docs/**` or `mkdocs.yml`. Build it locally first: ```bash pip install -r docs/requirements.txt mkdocs build --strict ``` Strict mode fails on broken internal links, which is what the published build enforces too. ## Related - [Configuration](../reference/configuration.md) - [Errors](../reference/errors.md) - [Architecture](../architecture.md) --- # Action reference Source: docs/reference/action.md URL: https://docs.magmamoose.com/diatreme/reference/action/ Generated by `scripts/gen_action_reference.py` from `action.yml`. Edit the action, not this page. For the task-shaped version, see [Using the action](../action.md). ## Action inputs `MagmaMoose/diatreme@v2` — all 110 inputs are optional. | Input | Default | Description | | --- | --- | --- | | `mode` | `release` | Pipeline mode. One of: ci Build the Docker image and push it to the registry. On a pull request the tag is pr-<N>, which release promotes. On any other event (a push, a dispatch) it is <branch>-<sha7>-<commit time>, e.g. test-1a2b3c4-1760000000: immutable, and sortable by its last field, so a branch can be built and deployed before it has a pull request. The tag is the `image-tag` output. release (default) Run versioning, promote Docker image, and optionally create a promotion PR (when deployment-model is tbd-pr and create-promotion-pr is true). cut-release-branch Create `release/X.Y.Z` from the commit the workflow runs on, for the version in `version-override` (run it from workflow\_dispatch on the default branch). Refuses a version already released or not above the newest release, unless the workflow runs on a stable tag of that line, which reopens it for a patch. Created with an App token, the new branch starts the release workflow, which cuts its first candidate (see `release-branch-versioning: branch`). enable-auto-merge Enable native GitHub auto-merge on the PR referenced by `pr-number`. Intended for non-promotion (feature) PRs invoked from a separate `pull_request` workflow. The repository must have "Allow auto-merge" enabled and branch protection with at least one required status check on the target branch — both are GitHub prerequisites for auto-merge, not Diatreme ones. | | `auth-mode` | `public-app` | Token source for git/release operations. One of: public-app (default) Use the Diatreme GitHub App installed on the repository or organization. auto Use private-app when app-id/app-private-key are set, otherwise use github-token/GITHUB\_TOKEN. github-token Use github-token or the workflow GITHUB\_TOKEN. private-app Generate a token from app-id/app-private-key. | | `token-broker-url` | `https://api.diatreme.magmamoose.com` | Advanced override for the hosted Diatreme GitHub App auth service. Most repositories should not set this. | | `token-broker-fallback-url` | `https://broker-diatreme.magmamoose.com` | Secondary broker tried only when the primary is unreachable or returns 5xx. A broker hostname losing egress blocks releases in every repository pinned to every published version, and no shipped change can redirect those pins - so the fallback has to travel with the action itself. Set to an empty string to disable. Never used for 4xx: a rejected token is an answer, not an outage. | | `oidc-audience` | `diatreme` | Advanced override for public-app authentication. Most repositories should not set this. | | `versioning-tool` | `auto` | The versioning tool to use. One of: auto (default) Detect the tool from repository markers under `working-directory`. See the detection rules below. semantic-release-python python-semantic-release v10 semantic-release-npm semantic-release v24 (Node.js / JavaScript) gitversion GitVersion via gittools/actions release-please Google release-please-action v4 Autodetection (versioning-tool: auto) inspects `working-directory` in two tiers and errors if nothing matches or the signals conflict — set an explicit tool to opt out. Tier 1 — a tool's own release config (authoritative, one tool each): semantic-release-python pyproject.toml with a [tool.semantic\_release] table semantic-release-npm .releaserc\* / release.config.\* gitversion GitVersion.yml\|.yaml (or gitversion-config) release-please release-please-config.json / .release-please-manifest.json (or release-please-config-file) Two or more distinct tier-1 tools is a conflict → error. Tier 2 — ecosystem manifests (only when no tier-1 config is found): semantic-release-python pyproject.toml / setup.py / setup.cfg semantic-release-npm package.json gitversion \*.csproj / \*.sln When several tier-2 manifests coexist, a fixed precedence (python → npm → gitversion) breaks the tie so a Python service that also carries a package.json still resolves to python. | | `deployment-model` | `tbd` | Controls how the target environment is determined. One of: tbd (default) Trunk-Based Development. Pass `environment` explicitly. bbd Branch-Based Development. Environment inferred from branch-map. tbd-pr TBD with PR-based promotion. Environment detected from the merged promote/\* PR head branch. | | `branch-map` | not set | JSON object mapping branch names to environment names. Only used when deployment-model is bbd. Plain BBD (one branch per environment): {"dev": "dev", "staging": "staging", "main": "prod"} Strict GitFlow (release/\* and hotfix/\* are dynamic branch families). Keys containing `*` are treated as globs — they match any segment up to the next slash boundary the same way shell globs do, anchored at both ends: {"develop": "dev", "release/\*": "staging", "hotfix/\*": "prod", "main": "prod"} Exact matches always win over globs. When two globs both match, the one with the longer key wins, so a specific pattern like `release/hotfix/*` beats `release/*`. `master` and `main` are interchangeable for exact-match lookup — a branch-map entry for `"main"` will match a `master`-default repo and vice versa, so the same map works across repos that haven't finished renaming. An explicit entry for either always wins over the implicit alias. | | `promote-branch-prefix` | `promote` | Prefix for promotion PR branches (deployment-model: tbd-pr). Example: 'promote' → branch promote/staging/1.2.3-dev.1 | | `promote-target-branch` | `main` | Target branch for promotion PRs. | | `create-promotion-pr` | `false` | When true, automatically creates the next environment promotion PR after a prerelease (deployment-model: tbd-pr only). Set to false when using a separate promotion workflow or manual process. One open promotion PR per target environment: if an open promotion PR already exists for the next environment (any version), its title and body are refreshed to the latest tag instead of opening a duplicate. Reviewers should click "Update Branch" on the existing PR before merging so the cut reflects the latest commits on the target branch — the version in the PR title is metadata; the cut version is derived from the merged commit history. | | `deploy-paths` | not set | JSON array of directories where deployments are written rather than code: the kustomize overlays a deploy tool moves image tags in by pull request, such as Tremvok's `gitops-pr`. Empty (the default) turns this off. ["k8s/overlays/acc", "k8s/overlays/prd"] `mode: ci` skips the image build and scan for a pull request that changes nothing outside them, and still reports its check. `mode: release` refuses a push that changes nothing outside them, before anything is tagged: merging a deploy PR is a deployment, and releasing it would publish a release that opens a deploy PR for the new version in turn. Add the same directories to the push trigger's `paths-ignore`; the refusal is for when that is missing. | | `environment` | not set | The target environment for this run. Must be in `environments`. Required when deployment-model is tbd. | | `environments` | `["dev", "staging", "prod"]` | JSON array of environment names in promotion order. The last entry is always treated as production (stable semver). Profiles: ["dev","prod"] \| ["dev","staging","prod"] \| ["dev","tst","acc","prd"] | | `prerelease-identifiers` | `{"dev": "dev", "staging": "rc"}` | JSON object mapping environment names to prerelease identifier strings. The production environment must be omitted from this map. Example: {"dev": "dev", "staging": "rc"} | | `tag-prefix` | `v` | Version tag prefix. | | `github-token` | not set | GitHub token for GHCR login and, unless auth-mode uses a GitHub App, git push, tag creation, GitHub Releases, and promotion PR creation. Defaults to the workflow GITHUB\_TOKEN when omitted. | | `app-id` | not set | GitHub App ID. When provided with app-private-key, generates a short-lived token to bypass branch protection rules. | | `app-private-key` | not set | GitHub App private key (PEM). Required when app-id is set. | | `submodules` | `false` | Pass-through to actions/checkout's `submodules` input on diatreme's internal checkout step. When set non-false in `auth-mode: private-app` or `auth-mode: auto` with App credentials, the App installation token is also broadened from the current-repo scope to the owner scope so submodules from sibling repositories in the same org can be fetched. The App must be installed on the submodule's repo for that broadened scope to actually grant access. For `auth-mode: github-token` / `public-app`, the configured token must have read access to the submodule repository — the action does not generate a separate token in those modes. One of: false (default) Skip submodules. true Fetch submodules at the recorded SHA, one level deep. recursive Fetch submodules and nested submodules. | | `image_name` | not set | Base image name without registry or owner prefix (e.g., my-app). Sets IMAGE\_NAME=<owner>/<image\_name> for the bake file. Optional — when omitted, Diatreme auto-detects it from the Docker Bake config (`bake_file` / `bake_target`): it runs `docker buildx bake --print`, takes the first non-empty target tag, and strips the digest, tag, registry, and owner/org prefix down to the base name. An explicit value always wins over detection. Detection drives the same image workflows an explicit value does — the CI image build (mode: ci), the image scan (image-scan), and release image promotion (mode: release). So mode: ci and BBD release promotion work without passing image\_name as long as the bake file has tagged targets. With no bake file present and no explicit value, image\_name is left empty and image workflows are skipped (versioning-only runs are unaffected). A bake file that exists but yields no tags is a hard error — Diatreme never falls back to the repository name. To keep a tagged bake file but run versioning only, set `detect-image-name: false` to opt out of detection entirely. | | `bake_file` | `docker-bake.hcl` | Path to the Docker Bake file. When it (or `docker-bake.json`, when this is left at the default) exists, Diatreme builds with `docker buildx bake`. When NO bake file is present but a `dockerfile` exists, Diatreme falls back to building it directly with `docker buildx build` (and emits a warning nudging you toward a bake file). See the `dockerfile` input. | | `bake_target` | `default` | Bake target or group to build/promote. Groups are expanded — all sub-targets are built/promoted automatically. | | `dockerfile` | `Dockerfile` | Path to the Dockerfile used by the no-bake fallback. When no Docker Bake file is present (see `bake_file`) but this file exists, Diatreme builds the image directly with `docker buildx build -f .` — honouring the same `platforms`, tags, provenance labels, GHA cache, `build-github-token` secret, and `--push` semantics as the bake path. This makes the simplest consumer (one Dockerfile, no bake file) Just Work. Prefer a `docker-bake.hcl` when you need multi-target builds, tag templating, multi-arch defaults, or local↔CI build parity — Diatreme emits a warning on the fallback path to point you there. | | `detect-image-name` | `true` | When true (default) and `image_name` is empty, auto-detect the base image name from the Docker Bake config (see `image_name`). Set to false to opt out of detection: `image_name` then behaves as it did before this feature — an empty value leaves image workflows off. This is the escape hatch for a repo that keeps a tagged `docker-bake.hcl` but runs Diatreme for versioning only (no image build/promotion) and so does not want a bare `mode: ci`/`release` run to start building or promoting images. An explicit `image_name` always wins regardless of this flag. | | `registry` | `ghcr.io` | Container registry | | `registry-username` | not set | Username for `docker login` against `registry`. Defaults to `github.actor` when blank, which is what GHCR on github.com expects. Override when targeting a registry that requires fixed credentials — e.g. GitHub Enterprise Server's container registry (`containers.`), Harbor, JFrog Artifactory, Nexus, Azure Container Registry. Pass a workflow secret, typically `secrets.REGISTRY_USERNAME`. When set, you should also set `registry-password`. The pair is used verbatim for both CI image pushes (`pr-` tags) and release image promotion. | | `registry-password` | not set | Password / token for `docker login` against `registry`. Defaults to the workflow's `GITHUB_TOKEN` (the `github-token` input, or `github.token` when that is blank), which is what GHCR on github.com expects. This is independent of the token used for git operations — git ops use the GitHub App installation token under `auth-mode: private-app` or `public-app`, but registry login always falls back to the workflow token. Override when targeting a registry that requires fixed credentials. Pass a workflow secret, typically `secrets.REGISTRY_PASSWORD`. When set, you should also set `registry-username`. The pair is used verbatim for both CI image pushes and release image promotion. | | `platforms` | not set | Target platforms (comma-separated), e.g. "linux/amd64,linux/arm64". Empty (the default) DEFERS to the repo's docker-bake.hcl — its own `variable "PLATFORMS"` default / target `platforms` decides. Set this only to force platforms regardless of the bake file. (Previously this defaulted to linux/amd64 and was exported unconditionally, silently overriding a repo's multi-arch bake default → amd64-only images.) | | `build-github-token` | not set | Optional token passed as --secret id=github\_token to docker buildx bake. Use when Dockerfiles use --mount=type=secret,id=github\_token to pull private packages (e.g. GitHub Packages). Pass secrets.NPM\_TOKEN or secrets.GITHUB\_TOKEN from the calling workflow. | | `image-skip-existing` | `false` | Skip re-publishing an image whose release tag ALREADY POINTS AT the exact manifest this run was about to publish. Lets a partially-failed multi-target promote resume without redoing the targets that landed, and makes a re-run of a completed promote a no-op. The test is identity, not existence. A tag is a mutable pointer that any holder of `packages: write` on the registry can create, so "a tag with that name is there" is no evidence this pipeline put it there — skipping on that alone would let an image Diatreme never built be released, signed and attested. The gate therefore compares manifest digests, runs only AFTER the provenance check on the promote source, and on a stable release additionally requires `:latest` to resolve to the same digest (otherwise an interrupted promote that wrote the version tag but not `:latest` would be recorded as done while `:latest` still served the previous release). Anything unproven — a registry error, an unreadable manifest, a digest that differs — falls through and does the work. It cannot short-circuit the fresh-build fallback: a rebuild's digest is not knowable in advance, so a release whose source image failed provenance verification is rebuilt on every run. That is a real limit of the gate, not an oversight. Off by default: re-cutting the same version deliberately (a force-pushed tag) must still republish. | | `image-scan` | `false` | Scan the built image and emit its SBOM + findings. In `mode: ci` this scans the pr-<N> candidate for the gate; in `mode: release` it scans the promoted release tag and ships the results to the configured sinks. Off by default. Requires `image_name`. | | `image-scan-severity` | `CRITICAL,HIGH` | Trivy `--severity` filter for findings and the optional gate (comma-separated). The CycloneDX SBOM still inventories all components. | | `image-scan-scanners` | `vuln,secret,misconfig` | Trivy `--scanners` to run for the findings report. Default covers OS/lib CVEs, secrets baked into layers, and image misconfigurations. | | `image-scan-gate` | `false` | Block the build when findings at/above `image-scan-severity` exist. Default false (non-blocking, visibility only) — start here and tighten later. This is a blunt severity threshold; net-new diffing against the base image is the intended direction. `mode: ci` only: by release time the tag is cut and the image pushed, so a gate there could only paint a finished release red, never un-ship it. | | `image-scan-strict` | `false` | Treat a \*sink\* failure (Dependency-Track / DefectDojo unreachable or rejecting) as fatal instead of a non-blocking warning. Default false — reporting backends stay failure-isolated, so an outage never fails the PR. | | `image-sign` | `false` | Sign the released image(s) with cosign (keyless / Sigstore) and attach SLSA build provenance (GitHub Artifact Attestations), by IMMUTABLE DIGEST, in `mode: release` after promotion/build. Off by default. Requires `id-token: write`, `attestations: write`, and `packages: write` on the job. Verify with `cosign verify …` and `gh attestation verify oci://… --owner `. | | `dependency-track-url` | not set | Dependency-Track base URL (e.g. `https://dtrack.example.com`). When set, the RELEASED image's CycloneDX SBOM is uploaded as the assembled-image project — distinct from any source-dependency SBOM project for the same repo. Uploads happen in `mode: release` only; the pr-<N> scan reports nowhere. Empty disables the sink. Outages are non-blocking. | | `dependency-track-api-key` | not set | Dependency-Track API key with BOM upload permission. Pass a workflow secret. | | `dependency-track-project-name` | not set | Dependency-Track project name. Defaults to the image repository path (e.g. owner/app). With multiple bake targets, the image leaf name is appended to keep the projects distinct. | | `dependency-track-project-version` | not set | Dependency-Track project version. Defaults to the released image tag (e.g. v1.2.3). | | `dependency-track-project-tags` | not set | Extra Dependency-Track project tags, comma-separated (e.g. "team:platform"). `repo:` and `sbom:image` are always added: an image project is named after the IMAGE, and a repo may build several (dunmir -> dunmir-agent, -backend, -frontend), so the project name alone cannot say which repo produced it. Only this workflow knows both, and a consumer grouping a repo's projects needs that join key. | | `dependency-track-auto-create` | `true` | Create the Dependency-Track project/version on first upload. Default true (the API key then needs PROJECT\_CREATION\_UPLOAD in addition to BOM\_UPLOAD). | | `defectdojo-url` | not set | DefectDojo base URL (e.g. `https://dd.example.com`). When set, the RELEASED image's Trivy findings report is imported (`mode: release` only, like the Dependency-Track sink). Empty disables the sink. Outages are non-blocking. Optional — the SBOM → Dependency-Track feed already yields component CVEs; this adds OS CVEs / misconfigs / secrets. | | `defectdojo-api-key` | not set | DefectDojo API v2 token. Pass a workflow secret. | | `defectdojo-engagement` | not set | DefectDojo engagement id to import into. If empty, set `defectdojo-product-name` to import via auto-created context instead. If both are empty while `defectdojo-url` is set, the import is skipped with a warning (non-blocking). | | `defectdojo-product-name` | not set | DefectDojo product name for the auto-create-context import path (used when `defectdojo-engagement` is empty). | | `defectdojo-product-type` | not set | DefectDojo product type for the auto-create-context path (optional). | | `defectdojo-engagement-name` | not set | DefectDojo engagement name for the auto-create-context path. Default "Diatreme image scan". | | `defectdojo-close-old` | `true` | Close findings that are no longer present, on reimport. Default true. Diatreme imports via DefectDojo's reimport-scan so one Test per engagement is updated across PR re-runs (mirrors Chargate). | | `publish-package` | `false` | When true, pack and push a language package to `package-feed-url` after versioning, using the version diatreme computed (the `version` output). Off by default so existing image-promotion / versioning-only consumers are unaffected. Runs only when a new version was released (`released == true`), after Docker image promotion and before the GitHub Release is published — so a `release:published` listener finds the package already in the feed (same ordering rationale as images). | | `package-ecosystem` | not set | Package ecosystem to publish when `publish-package` is true. One of: nuget .NET — `dotnet pack` + `dotnet nuget push`. npm Node.js — `npm publish`. maven JVM — `mvn versions:set` + `mvn deploy`. gradle JVM — `gradle publish` (project's maven-publish block). rubygems Ruby — `gem build` + `gem push`. container OCI image — `docker build` + `docker push` (ghcr.io). helm Helm chart — `helm package` + `helm push` to an OCI registry. `package-path` is the chart directory; the chart's version AND appVersion are both set to the released version, so a chart can never ship pointing at the previous image (`helm-app-version` changes what appVersion carries). `helm-lint`, `helm-sign` and the `artifacthub-*` inputs make it a public, signed chart. pip Python — `python -m build` + `twine upload` (PyPI / any index; not a GitHub Packages ecosystem, kept for convenience). All but pip are GitHub Packages ecosystems and default to this repo's GitHub Packages feed. Required when `publish-package` is true. | | `aws-role-to-assume` | not set | IAM role ARN the caller's OIDC step assumed, for `package-ecosystem: s3`. Required for that ecosystem. Only VERIFIED here (via `sts get-caller-identity`), so a workflow that forgot the credentials step fails with an actionable message rather than a 403 on upload. The role's trust policy is what decides who may publish — bind it to one repository and to its default branch plus tags, or every GitHub Actions workflow on github.com can assume it. | | `package-path` | not set | Project or path to pack/build/publish. Defaults to `working-directory`. nuget A .csproj/.sln/.nupkg path or a directory. npm The package directory (or a package.json path). maven The project dir or its pom.xml. gradle The project dir (or a build.gradle(.kts) path). rubygems The dir containing the .gemspec. helm The chart dir (the one with Chart.yaml). container The Docker build context (must contain a Dockerfile). pip The source dir containing pyproject.toml/setup.py. | | `package-feed-url` | not set | Upload / publish endpoint. Accepts a public GitHub Packages host, a canonical public registry (npmjs / nuget.org / rubygems.org / Maven Central / PyPI) for public distribution, or a GitHub Enterprise host — Enterprise Server `.HOSTNAME` or data-residency `.SUBDOMAIN.ghe.com`. The auth model is unchanged; only the host differs. Empty defaults per-ecosystem (the repo's GitHub Packages feed, except npm/pip which default to the public registry): nuget NuGet v3 index. Default `https://nuget.pkg.github.com/<owner>/index.json.` npm npm registry. Default `https://registry.npmjs.org` (public). maven Maven repo URL. Default `https://maven.pkg.github.com/<owner>/<repo>.` gradle Informational only — the repository is defined in build.gradle. rubygems Gem host. Default `https://rubygems.pkg.github.com/<owner>.` helm OCI registry. Default ghcr.io; the repository path defaults to <owner>/charts and is lowercased for you, because OCI names must be lowercase and `github.repository_owner` is not. container Image registry host. Default ghcr.io; set this to publish to another registry, e.g. an enterprise containers.HOSTNAME. pip twine repository URL (--repository-url). Empty publishes to PyPI. Note: the GitHub Packages Apache Maven registry is not available on data-residency (\*.ghe.com) tenants — use your enterprise Maven host there. | | `package-token` | not set | Auth token / API key for the package feed. Defaults to the workflow GITHUB\_TOKEN (the `github-token` input, or `github.token`), which is what GitHub Packages feeds expect with `packages: write`. This is the registry-login token, independent of the git/release auth token — pass a workflow secret (e.g. secrets.NUGET\_FEED\_TOKEN) when targeting a feed that requires fixed credentials, such as a GitHub Enterprise Packages feed on another host. | | `package-username` | not set | Feed / registry-login username. Defaults to `__token__` for `pip` (twine) and `x-access-token` for `maven`/`gradle`/`rubygems`/`container`. Ignored by `nuget` and `npm`, which authenticate with the token alone. | | `dotnet-version` | `8.0.x` | .NET SDK version range for `package-ecosystem: nuget`, passed to actions/setup-dotnet. Override to match the project's target framework (e.g. 9.0.x). Multiple versions can be newline-separated. | | `python-version` | `3.x` | Python version for `package-ecosystem: pip`, passed to actions/setup-python. | | `node-version` | `20` | Node.js version for `package-ecosystem: npm`, passed to actions/setup-node. | | `java-version` | `17` | Java (JDK) version for `package-ecosystem: maven` / `gradle`, passed to actions/setup-java. | | `java-distribution` | `temurin` | JDK distribution for `package-ecosystem: maven` / `gradle`, passed to actions/setup-java (e.g. temurin, zulu, corretto). | | `ruby-version` | `3.3` | Ruby version for `package-ecosystem: rubygems`, passed to ruby/setup-ruby. | | `package-name` | not set | Image name for `package-ecosystem: container`, published as `/:`. Defaults to the repository (owner/repo) lowercased. For `package-ecosystem: helm` it is the OCI repository path the chart is pushed under, default `/charts`. Ignored by the other ecosystems, which take their name from the project manifest. | | `npm-provenance` | `false` | When true, publish npm packages with build provenance (`npm publish --provenance`). Valid only for the public npm registry (registry.npmjs.org) — the run fails if package-feed-url points elsewhere, since GitHub Packages and other registries don't accept npmjs provenance attestations. Requires `id-token: write` on the job (the default `auth-mode: public-app` already grants it) and a public `repository` field in package.json matching the publishing repo. Ignored unless package-ecosystem is npm. | | `pypi-trusted-publishing` | `false` | When true, authenticate pip/twine uploads via GitHub OIDC (PyPI Trusted Publishing) instead of package-token — no stored token. Valid only for public PyPI / TestPyPI; the run fails for any other index (private indexes keep using package-token). Requires `id-token: write` on the job (the default `auth-mode: public-app` already grants it) and a Trusted Publisher configured for this repo+workflow on the PyPI project. Ignored unless package-ecosystem is pip. | | `helm-app-version` | `version` | What the chart's `appVersion` is set to. The chart's `version` is always the released version. One of: version (default) The released version, e.g. 1.4.0. tag The release tag, e.g. v1.4.0: the tag image promotion pushes. Use it when the chart's default image tag is `.Chart.AppVersion` and `tag-prefix` is not empty, or the published chart points at an image tag that does not exist. chart Keep the appVersion committed in Chart.yaml, for a chart that packages an image this repository does not build. | | `helm-lint` | `false` | When true, `helm lint` the chart before packaging it and publish nothing if it fails. | | `helm-sign` | `false` | When true, sign the pushed chart with cosign (keyless / Sigstore) by immutable digest, which Artifact Hub shows as a signed chart. Requires `id-token: write` on the job (the default `auth-mode: public-app` already grants it). A re-run that finds the version already published signs the digest the registry holds, so a run that pushed but failed to sign can be re-run into a signed chart. | | `artifacthub-repo-file` | not set | Path to an `artifacthub-repo.yml` to push next to the chart, as the chart repository's `artifacthub.io` tag. Artifact Hub reads it for Verified Publisher (`repositoryID`) and ownership claims (`owners`). Empty pushes nothing. | | `artifacthub-api-key-id` | not set | Artifact Hub API key ID. With `artifacthub-api-key-secret`, the chart's OCI repository is added to Artifact Hub when it is not listed there yet (Artifact Hub lists one repository per OCI chart; an existing one is left alone). Its ID comes back in the `artifacthub-repository-id` output and the job summary, for `repositoryID` in artifacthub-repo.yml. Pass a workflow secret. | | `artifacthub-api-key-secret` | not set | Artifact Hub API key secret, paired with `artifacthub-api-key-id`. Pass a workflow secret. | | `artifacthub-org` | not set | Artifact Hub organization to add the chart repository under. Empty adds it under the user who owns the API key. | | `artifacthub-repository-name` | not set | Name of the chart's repository on Artifact Hub, which appears in its package URLs and is unique across Artifact Hub. Lowercase letters, digits and hyphens, starting with a letter. Defaults to the chart's name. | | `issue-reference` | not set | Require a pull request to reference an issue (mode: ci, pull\_request events). Empty (the default) checks nothing. One or both of: title The pull request title must reference an issue. A squash merge makes the title the commit's subject, and a merge commit carries it in its body, so this is the check for either. commits Every commit in the pull request must, apart from merge commits. For rebase merges, where each commit lands as it is. `title, commits` checks both. A reference is anything GitHub links to an issue: `#123`, `GH-123`, `owner/repo#123` or an issue URL. Bot branches (dependabot/, renovate/), Diatreme's own branches and deploy-only pull requests (see `deploy-paths`) are not checked. With `title`, add `edited` to the workflow's pull\_request types so fixing the title re-runs the check. | | `enforce_branch_naming` | `true` | Enforce TBD branch naming convention on PRs (mode: ci). Allowed prefixes: feat, fix, chore, hotfix, docs, refactor, perf, test, ci, style, build, revert, deploy, release, claude, codex (plus the promote prefix and merge-back). Add more via extra-branch-prefixes, or replace them with your own convention via branch-name-patterns. Set to false for BBD (branches are named after environments). | | `extra-branch-prefixes` | not set | Additional branch-name prefixes to accept beyond the built-in set (mode: ci, enforce\_branch\_naming: true). Comma-, space-, or pipe-separated. Example: 'spike wip' accepts spike/\* and wip/\* branches. Each prefix must be letters, digits, '\_' or '-' (a trailing '/' is allowed and ignored). Anything else is rejected: the prefixes are matched as a regex, where a metacharacter would silently widen or break the check rather than add a prefix. | | `branch-name-patterns` | not set | Whole branch names a pull request may come from, replacing the built-in types and `extra-branch-prefixes` (mode: ci, enforce\_branch\_naming: true). One pattern per line, or comma-separated. Empty (the default) keeps the built-in types. feature/{issue}-{name} hotfix/{issue}-{name} release/{version} Placeholders: {issue} an issue number (digits) {version} major.minor.patch, no leading zeros {name} lowercase words joined by single hyphens, e.g. search-filter \* anything within one path segment \*\* anything, across segments (e.g. deploy/\*\* for deploy PRs) Everything else is literal and the whole name must match, so `release/{version}` refuses `release/1.4` and `release/1.4.0-rc1`. An unknown placeholder is an error. Bot branches (dependabot/, renovate/) and Diatreme's own (the promote prefix and merge-back/) are always accepted. | | `image-commit-tag` | `false` | Also push a pull request's ci image as `pr--`, where sha7 is the first 7 characters of the pull request's head commit (mode: ci, pull\_request events). `pr-` is overwritten on every push, so a deploy pinned to it never rolls; a preview controller that renders one deploy per head commit (Flux Operator's `GitHubPullRequest` provider, Argo CD's pull request generator) uses this tag instead. It is the head commit, not `github.sha`: that is the merge commit actions/checkout builds, which those controllers do not know. The tag goes out in the same push as `pr-`, so both name one manifest. A pull request whose build is skipped (see `deploy-paths`) gets it by retagging its existing `pr-`, and a warning when there is none yet. The tag is the `image-commit-tag` output. Other events and `mode: release` are unchanged. | | `image-building-label` | not set | A label that is on a pull request while mode: ci builds its images. Empty (the default) turns this off. Added before the build and removed only once every tag (with `image-commit-tag`, the commit tag too) is pushed; a run that fails or is cancelled leaves it on. A preview controller that holds a pull request while it carries the label (Flux Operator's ResourceSetInputProvider `spec.skip.labels`) keeps the preview on the last commit that has an image. Label changes never fail the run, they warn. They use the token Diatreme already resolves, which needs `pull-requests: write`. Keep `labeled` and `unlabeled` out of the workflow's pull\_request types: a label changed with an App token starts workflows, so each change would start another build. A run that this label started does not add it again, so it cannot loop. | | `aggregate-github-projects` | `false` | When true, after a release is created, walk the commits in the release range and the bodies of any PRs landed in that range, collect issue and PR references (#NNN), look up their Projects v2 membership via the GitHub GraphQL API, and append a "## GitHub Project items" section (grouped by Project, with the item's Status when available) to the GitHub Release notes and to any open promotion PR body that mentions the tag. The auth token must have: - Repository: Contents: Read - Repository: Issues: Read - Repository: Pull requests: Read - Repository: Releases: Write (to edit release notes) - Repository: Pull requests: Write (to edit promotion PR bodies) - Organization or User: Projects: Read With auth-mode: public-app, the default Diatreme App ships with only the permissions needed for tagging and Releases. Issues, Pull requests, and Projects must be granted on the App settings AND re-accepted on each installation; otherwise the GraphQL probe that finds a ref's Projects v2 membership returns NOT\_FOUND for every issue/PR (the script logs "Ref #N: GraphQL returned no node" with the underlying error and skips the ref). With auth-mode: github-token, the workflow GITHUB\_TOKEN cannot read org-scoped Projects v2 — supply a PAT with `repo` and `read:project` (or fine-grained equivalents). | | `move-github-projects-on-release` | `false` | When true, after a release is created, move every Projects v2 item linked to issues/PRs in the release range to a target Status. Intended for closing the loop on releases — e.g. moving "In review" cards to "Released" when the prod tag is cut. Set `github-projects-target-status` to the Status value to move to (must already exist on the Project). The status move is opt-in because not every project board has a "Released" column. Skipped silently when the project's Status field has no matching option. Works alongside `aggregate-github-projects` — the two are independent toggles, and they need the same Issues + PRs + Projects read scopes (see aggregate-github-projects). For the move itself the token must additionally have Organization or User: Projects: Write. With auth-mode: github-token, supply a PAT with `project` scope (read+write). | | `github-projects-target-status` | `Released` | Target Status name for `move-github-projects-on-release`. Must match an existing single-select option on each project's Status field. Common values: 'Released', 'Done', 'Shipped'. | | `github-projects-move-on-environments` | `@last` | JSON array of environments where the auto-move should fire. Defaults to the production environment only (last entry of `environments`), so prereleases don't prematurely mark items released. Special values: '@last' (default) Resolve at runtime to the last entry of `environments`. Production-by-default in any naming. '[]' Move on every environment. Or a literal JSON array of environment names, e.g. '["staging","prod"]'. | | `admin-required-from` | `@last` | Threshold environment for the manual-release guardrail. Manual workflow\_dispatch runs whose target environment is at or after this threshold (in the `environments` list) require the actor to have `permission: admin` on the repository. Push and promotion-PR-merge triggers are unaffected. Special values: '@last' (default) Use the last entry in `environments`. With the default environments=["dev","staging","prod"] this protects prod only; with environments=["dev","tst","acc","prd"] it protects prd only. The point is to give every consumer production protection out of the box without needing to know the literal env name. '' Opt out. No manual-release guardrail. Or set to a specific environment name (must appear in `environments`) to gate that env and everything downstream. Examples (environments = ["dev","staging","prod"]): '@last' → only prod releases require admin (default) prod → only prod releases require admin staging → staging and prod require admin dev → all envs require admin '' → no guardrail The auth token must allow Repository: Administration: Read. With auth-mode: public-app, grant the permission on the Diatreme App and accept it on the installation. | | `allowed-release-actors` | not set | Restrict who may cut a release at or after `allowed-release-actors-from`. Comma-separated GitHub logins, and/or teams as `@org/team-slug` (or `@team-slug`, which resolves against this repository's owner). A JSON array is also accepted. Matching is case-insensitive. Empty (the default) leaves releases unrestricted — the gate is inert until you populate it. Unlike `admin-required-from` this applies on every trigger, not only `workflow_dispatch`, and it names people rather than asking for the much broader repo-admin grant. The two are independent; both are enforced when both are set. Include any bot login that merges promotion PRs on your behalf, or the release those merges trigger will be refused. Team lookups need the token to be able to read org team membership. Listing only plain logins needs no extra permission. A membership lookup that cannot be completed denies the release rather than allowing it. | | `allowed-release-actors-from` | `@last` | First environment (by position in `environments`) at which `allowed-release-actors` is enforced. `@last` resolves to the final entry, i.e. production only. Same semantics as `admin-required-from`. | | `suite-manifest` | not set | Version-only suite release: Kustomize manifest containing the centrally selected images/newTag values. Requires suite-catalog; app repositories are read-only. | | `suite-catalog` | not set | Version-only suite release: JSON catalog with apps [{id, display\_name, repository, image}]. Aggregates every changed app release into CHANGELOG.md and release.json. | | `working-directory` | `.` | Working directory containing the versioning config file. For semantic-release-python: pyproject.toml For semantic-release-npm: .releaserc.json / package.json For gitversion: GitVersion.yml | | `create-release` | `true` | Create a GitHub Release on every version bump. | | `changelog` | `true` | Generate/update CHANGELOG.md (semantic-release-python and semantic-release-npm). | | `force-bump` | not set | Force a specific version bump instead of letting the versioning tool decide from commit messages. Designed for `workflow_dispatch` runs where there are no qualifying conventional commits since the last release but you still want to cut a new version (the typical "no\_release / Released: false" outcome). Allowed values: patch Force a patch bump (e.g. 1.2.3 → 1.2.4). minor Force a minor bump (e.g. 1.2.3 → 1.3.0). major Force a major bump (e.g. 1.2.3 → 2.0.0). '' (default) Let the versioning tool decide. Honoured by: - semantic-release-python: passed as the upstream `force` input. - semantic-release-npm: commit-message gating is skipped and the next version is derived by bumping the latest stable tag at the requested level. On prerelease branches this cuts the next `-.N` tag; on stable branches the tag is created directly and semantic-release itself is skipped, so config-driven publish plugins (changelog commit, npm publish, ...) do not run for that release — the GitHub Release still comes from the deferred publish step. Promotion PRs ignore it (their version always comes from the promoted tag). - gitversion: GitVersion still runs, but the next version is derived by bumping the latest stable tag at the requested level rather than from GitVersion's computed `majorMinorPatch`. It is NOT passed as `overrideConfig: increment=…`: that sets GitVersion's root `increment` key, which a branch's own `increment` overrides, so a config pinning `branches: main: increment: Patch` silently ignored the forced bump and cut a patch anyway. Ignored by release-please — it has no clean equivalent and a forced bump would conflict with the tool's own logic. Wire your `workflow_dispatch` `bump` input to this input from the caller workflow. | | `version-override` | not set | Explicit version to release/build. Accepts SemVer with optional `v` prefix, e.g. `3.20.0` or `v3.20.0-rc.1`. When set, diatreme skips automatic version calculation and uses this value for release tag/image versioning. The optional `v` prefix is stripped only for `${VERSION}` substitution in bake/build args. Mutually exclusive with `force-bump`. In `mode: cut-release-branch` it is the version the branch is cut for, and must be a plain `X.Y.Z`: the branch is named `release/X.Y.Z`. | | `release-branch-versioning` | `auto` | On a stable branch, take the release version from the `release/X.Y.Z` or `hotfix/X.Y.Z` branch named in HEAD's merge subject instead of inferring it from commit messages. Why this is on by default: in GitFlow the release branch name states the version, but every versioning backend infers the bump from commit messages, and that inference does not survive a squash merge. "Squash and merge" collapses the branch's `feat:`/`fix:` commits into one commit whose body is a bullet list, so the `^feat:` anchors stop matching and the tool falls back to the trunk's default increment — a patch. `release/1.15.0` then ships as `1.14.5`, every step green, and that mislabelled image is what the cluster pulls. Allowed values: auto (default) Derive the version when HEAD's subject names a release/hotfix branch, the target environment is the stable one, and the derived version is ahead of the latest released tag. Otherwise the configured versioning tool decides, unchanged. branch Everything `auto` does, and version a run ON a release branch from that branch's own name, in any environment and with no versioning tool, so commit messages need not be conventional. `release/1.4.0` cuts 1.4.0 (`1.4.0-rc.N` in a prerelease environment) until 1.4.0 is released, then the next free patch: a hotfix merged into `release/1.4.0` once v1.4.0 shipped cuts `1.4.1-rc.1`. A re-run on a commit that already holds its candidate resumes that release, and a commit already released as a stable version of the line releases nothing. A branch whose name holds no X.Y.Z is left to the versioning tool. off Never derive; the versioning tool always decides. Skipped when `version-override` or `force-bump` is set — an explicit instruction from the caller always outranks the branch name. | | `release-branch-merge-back` | not set | Branch to merge a release branch back into after a stable release from it, e.g. `master`, or `@default` for the repository's default branch. Empty (the default) turns this off. After a stable release whose commit sits on a `release/X.Y.Z` branch (a `promote-from` of one of its candidates, or a run on the branch itself), Diatreme opens a pull request merging that branch into this one, so the hotfixes released from it reach every later release. Nothing is opened when this branch already contains the release branch's head, which is the case for a release with no hotfixes. The pull request comes from `merge-back/release-X.Y.Z`, a branch that starts at the release branch's head, never from the release branch itself: "Update branch" and conflict resolution on a pull request commit the target INTO its head branch, and the release branch must keep building exactly what is deployed. Later releases from the same line move that branch forward and reuse the open pull request. Merge it with a merge commit; a squash copies the changes instead of carrying the release branch's history. Needs a token that can create branches and pull requests (the default `auth-mode: public-app` can). | | `release-branch-cleanup` | `false` | When true, a stable release deletes the release branches (`release/X.Y.Z`, `releases/X.Y.Z`) of OLDER lines, by major.minor, whose head is already in `release-branch-merge-back` (or the default branch when that is not set). The released line and any newer one are kept, and so is an older line with commits the target lacks, with a notice. What a deleted line shipped stays reachable through its tags; `mode: cut-release-branch` run on its latest tag recreates the branch to patch it. Off by default. | | `promote-from` | not set | Promote an existing prerelease to its stable version instead of cutting a new release. Takes the prerelease's git tag, with or without `tag-prefix` (`v1.5.0-rc.3` or `1.5.0-rc.3`), and releases that exact build as `v1.5.0`. For flows where no branch ever builds a stable version: a release branch cuts `-rc.N` prereleases, one of them is signed off, and that build is what ships. Pass the approved tag from a `workflow_dispatch` workflow. What a promotion does differently from an ordinary release: version The source tag's own, minus its prerelease part. No versioning tool runs; `version-override` and `force-bump` are rejected. commit The run checks out the source tag's commit, so the stable tag lands on the commit the image was built from, whichever ref the workflow was started on. A published package is built from that commit too. image Each image is retagged from `:`. A source image the registry reports missing fails the run BEFORE the stable tag is pushed, and a failed retag fails it too. There is no fresh-build fallback: a rebuild is not the build that was tested. :latest Moves only when the promoted version is the highest stable version under `tag-prefix`. Promoting a fix on an older release line (1.4.3 once 1.5.0 is out) leaves it alone. notes The GitHub Release lists what changed since the previous stable tag, not since the prerelease being promoted. environment Always the last entry of `environments`, whatever `deployment-model`, `branch-map` or the triggering branch say. `admin-required-from` and `allowed-release-actors` apply as they do to any production release. The source must carry the prerelease identifier of the environment just before the last one in `environments` (usually `rc`), when that environment has one. Promoting a `-dev.N` build to stable is refused. Safe to re-run. The stable tag records the prerelease it was promoted from (a `Promoted-From:` line in its message). Finding that tag already in place resumes the promotion and finishes whatever did not land. Any other existing stable tag fails the run, whether it sits on another commit or was promoted from a different prerelease on the same one: a published stable version is never moved. `version-file` is not written on a promotion. The artifact is already built, and the run sits on a tag's commit rather than on a branch to commit to. Two combinations are refused, because each would undo the point of a promotion. `publish-package` with `package-ecosystem: container` builds a fresh image under the stable version. `npm-provenance` attests the package to the commit the workflow was started on, so it is accepted only when that is the promoted commit: start the workflow from the prerelease tag. For the same reason `image-sign` still signs a promoted image but attests SLSA provenance only when started from that tag. | | `version-file` | not set | Path to a JSON or YAML file where the released version is injected and committed back to the branch after every release. Works with every versioning tool, not just GitVersion. Typical uses: - JSON: persist the version into `appsettings.json` for a .NET app. - YAML: update `appVersion` in a Helm `Chart.yaml` so the chart tracks the released image tag automatically. Accepts one path, or several: separate them with newlines (preferred) or commas. Each entry may be a glob — `*` and `**` are expanded against the workspace — so a monorepo can sync every workspace manifest in one entry: version-file: \| package.json packages/\*/package.json All matched files are updated and committed together. A path that does not exist, a glob that matches nothing, or a file the path expression cannot be applied to is warned about and skipped; it never fails the release. File format is detected from the extension: `.yaml`/`.yml` files are processed with `yq`; all other files are processed with `jq`. The commit uses the resolved release auth token (Diatreme App, private app, or `github-token`), so it can bypass branch-protection rulesets when the App is in the bypass list. The commit message ends with `[skip ci]` so the push does not retrigger the release workflow. Leave empty to disable. The file must exist or the step is skipped with a warning. | | `version-file-json-path` | `.Application.Version` | jq path for the version field inside `version-file` when the file is JSON. Only used when `version-file` is set and the file is not a `.yaml`/`.yml` file. Example: `.Application.Version` | | `version-file-yaml-path` | `.appVersion` | yq path for the version field inside `version-file` when the file is YAML (`.yaml` or `.yml` extension). Only used when `version-file` is set and the file has a YAML extension. Example: `.appVersion` For Helm charts, set this to `.appVersion` (default) to update the application version, or `.version` to update the chart version, or a custom path for other YAML schemas. | | `aggregate-clickup-tickets` | `false` | When true, after a release is created scan the commits in the release range and the descriptions of PRs that landed in that range for ClickUp ticket URLs (`https://app.clickup.com/t/...`). Any matches are appended as a "## ClickUp tickets" section to the GitHub Release notes and to the auto-opened promotion PR body when one exists. The auth token must allow editing release notes and PR bodies. With auth-mode: public-app this is already covered by the Diatreme App. | | `gitversion-spec` | `6.x` | GitVersion version spec (e.g., 6.x). Only used when versioning-tool is gitversion. | | `gitversion-config` | not set | Path to a GitVersion config file. Only used when the resolved versioning tool is gitversion. Empty (the default) means Diatreme looks for a `GitVersion.yml` or `GitVersion.yaml` under `working-directory` and hands that to GitVersion, or lets GitVersion run on its built-in defaults when neither exists. Set this only to point at a config kept somewhere else — an explicit path that does not exist is an error. A relative path is resolved against `working-directory`, matching how autodetection scopes its markers. An absolute path is used as-is. | | `gitversion-appsettings-file` | not set | DEPRECATED — use `version-file` instead. Retained for backwards compatibility. When both are set, `version-file` wins. | | `gitversion-appsettings-version-path` | not set | DEPRECATED — use `version-file-json-path` instead. Retained for backwards compatibility. | | `release-please-release-type` | `simple` | release-please release type (python, node, simple, go, etc.). | | `release-please-config-file` | `release-please-config.json` | Path to release-please-config.json. | | `pr-number` | not set | Pull request number to operate on. Required for `mode: enable-auto-merge`. Typically passed as `github.event.pull_request.number` from a `pull_request` workflow (wrapped in the usual expression syntax in the caller's `with:` block). | | `auto-merge-method` | `squash` | Merge method used by `mode: enable-auto-merge`. One of: squash (default) Squash the PR's commits into a single commit on the target branch. merge Standard merge commit. rebase Rebase the PR's commits onto the target branch. | ## Action outputs | Output | Description | | --- | --- | | `version` | Semver version string without prefix (e.g., 1.2.3 or 1.2.3-rc.1) | | `tag` | Full git tag with prefix (e.g., v1.2.3 or v1.2.3-rc.1) | | `is-prerelease` | "true" if this environment produces a prerelease version | | `released` | "true" if a new version was created and published | | `prerelease-identifier` | The prerelease identifier (e.g., dev, rc, alpha). Empty for production. | | `resolved-environment` | The resolved environment name. | | `package-published` | "true" if a language package was packed and pushed to the configured feed. | | `artifacthub-repository-id` | Artifact Hub repository ID of the published chart (package-ecosystem: helm with the artifacthub-api-key-\* inputs set). | | `image-scanned` | "true" if the assembled pr-<N> image(s) were scanned (mode: ci with image-scan). | | `image-findings` | Count of image-scan findings at/above image-scan-severity across all scanned images. | | `image-signed` | Number of released image(s) cosign-signed (mode: release with image-sign). | | `resolved-image-name` | The base image name Diatreme used for image workflows — the explicit `image_name` input when set, the value auto-detected from the Docker Bake config, or the repository name on the no-bake Dockerfile path. Empty when none applies (versioning-only runs). | | `image-tag` | The tag mode: ci pushed its image under: pr-<N> on a pull request, <branch>-<sha7>-<commit time> on any other event, or version-override when set. Empty when no image was built. | | `image-commit-tag` | The per-commit tag a pull request's ci image also got with image-commit-tag: pr-<N>-<first 7 characters of the head commit>. Empty on other events, with the input off, or when no image could be tagged. | | `images-promoted` | Number of release image(s) retagged rather than rebuilt: from a provenance-verified pr-<N> image, from the previous environment's prerelease, or from the prerelease named by promote-from. | | `images-skipped` | Number of release image(s) already present in the registry and skipped via image-skip-existing. | | `images-rebuilt` | Number of release image(s) built fresh because provenance was unverified or the retag failed. | | `version-files-updated` | Number of tracked files the released version was injected into and committed. | | `promoted-from` | The prerelease tag this run promoted to stable, prefix included (mode: release with promote-from). Empty on every other run. | | `release-branch` | The release branch `mode: cut-release-branch` created (or found already on the commit), e.g. release/1.4.0. Empty in every other mode. | | `merge-back-pr` | URL of the pull request merging the release branch back (mode: release with release-branch-merge-back), whether opened by this run or already open. Empty when there was nothing to merge back. | | `release-branches-deleted` | Number of superseded release branches deleted (mode: release with release-branch-cleanup). | --- # Broker API Source: docs/reference/broker-api.md URL: https://docs.magmamoose.com/diatreme/reference/broker-api/ The broker is the GitHub App backend the action calls when `auth-mode` is `public-app`. The production Python/Lambda broker serves `POST /token` (the route the action uses). The retired Cloudflare Worker also served `POST /sign`, `GET /releases`, and `POST /webhook`; those are documented below for reference. Anything else returns `404 not_found`. Base URL for the hosted broker: ```text https://api.diatreme.magmamoose.com ``` `https://broker-diatreme.magmamoose.com` serves the same application and is the fallback the action tries when the primary is unreachable. See [Deployment](../operations/deployment.md) for which infrastructure answers each name. Every response is JSON. Every failure carries a stable `error` string, and `/token` verification failures also carry a coarse `reason`. Neither is localised and neither changes shape between versions, so you can match on them. ## POST /token Exchange a GitHub Actions OIDC token for a short-lived GitHub App installation token. This is the route `auth-mode: public-app` uses on every release. **Auth:** the OIDC token in the body. The calling job needs `id-token: write`. There is no API key. ### Request `Content-Type: application/json` | Field | Type | Required | Effect | | --- | --- | --- | --- | | `oidcToken` | string | yes | The Actions OIDC JWT, minted for the `oidc-audience` the broker accepts. | | `owner` | string | yes | Repository owner. Must match the token's `repository` claim. | | `repo` | string | yes | Repository name. Must match the token's `repository` claim. | | `ref` | string | no | Recorded for logging only. Never authorises anything. | | `runId` | string | no | Recorded for logging only. | | `sha` | string | no | Recorded for logging only. | ```bash curl -sS -X POST https://api.diatreme.magmamoose.com/token \ -H 'Content-Type: application/json' \ --data '{"oidcToken":"","owner":"MagmaMoose","repo":"diatreme"}' ``` ### Success `200 OK` ```json { "token": "ghs_xxxxxxxxxxxxxxxxxxxx", "expires_at": "2026-08-20T13:00:00Z", "repository": "MagmaMoose/diatreme" } ``` The token is a GitHub App installation token scoped to that one repository. Its permissions default to `contents: write` and `pull_requests: write`, overridable per deployment with [`TOKEN_PERMISSIONS`](configuration.md#token_permissions). GitHub sets the lifetime, currently one hour, and the broker passes `expires_at` through unchanged rather than computing it. The action masks the token in the run log and writes it to the step outputs `token`, `expires-at` and `repository`. ### Failures | Status | `error` | When | | --- | --- | --- | | 400 | `invalid_json` | Body isn't parseable JSON. | | 400 | `invalid_request` | Body parsed but isn't a JSON object. | | 400 | `missing_required_fields` | One of `oidcToken`, `owner`, `repo` is absent or empty. | | 400 | `invalid_token_permissions` | The deployment's `TOKEN_PERMISSIONS` is set but parses to nothing usable. A broker misconfiguration, not a caller error. | | 401 | `invalid_oidc_token` | The token failed verification. Carries a `reason`. | | 403 | `repo_mismatch` | The token's `repository` claim isn't `owner/repo`. | | 403 | `repo_not_allowed` | The repository is outside the deployment's `ALLOWED_REPOSITORIES`. | | 404 | `app_not_installed` | The Diatreme App isn't installed on that repository. | | 405 | `method_not_allowed` | Anything other than POST. | | 500 | `github_installation_lookup_failed` | GitHub answered the installation lookup with something unusable. | | 503 | `oidc_key_fetch_failed` | The broker couldn't retrieve the issuer's key set. Retryable. Carries `reason: jwks_unavailable`. | The split between 401 and 503 is deliberate and load-bearing. A 401 means the broker reached GitHub's key set and your token failed against it. A 503 means the broker never got a verdict. Retrying a 401 will not help. Retrying a 503 often will. Every `reason` value and its fix is in [Errors](errors.md#token-verification-failures). ## POST /sign Create a GitHub-signed, App-attributed commit on a branch through `createCommitOnBranch`. Diatreme uses it so version bumps and release commits show as verified and attributed to the App rather than to a person. **Auth:** `Authorization: Bearer `. Returns `503 sign_disabled` when that secret isn't configured, so a deployment that doesn't set it simply has no signer. ### Request | Field | Type | Required | Effect | | --- | --- | --- | --- | | `repo` | string | yes | `owner/name`. | | `branch` | string | yes | Branch to commit on. | | `expected_head_oid` | string | yes | The commit SHA the branch must currently point at. GitHub rejects the write if it moved, which is what makes this safe to retry. | | `message.headline` | string | yes | Commit subject. | | `message.body` | string | no | Commit body. | | `additions` | array | one of the two | `[{ "path": "...", "contents": "" }]`. | | `deletions` | array | one of the two | `[{ "path": "..." }]`. | | `user` | string | no | Accepted and ignored. Commits are App-attributed. | At least one of `additions` or `deletions` must be non-empty. ### Success `200 OK` with `{ "ok": true, "commit": { ... } }`, carrying GitHub's commit object. ### Failures | Status | `error` | When | | --- | --- | --- | | 400 | `invalid_json` / `invalid_request` | Malformed body. | | 400 | `missing_required_fields` | `repo`, `branch`, `expected_head_oid` or `message.headline` absent. | | 400 | `no_file_changes` | Both `additions` and `deletions` are empty. | | 400 | `invalid_repo` | `repo` isn't `owner/name`. | | 401 | `unauthorized` | Bearer missing or wrong. Compared in constant time. | | 405 | `method_not_allowed` | Anything other than POST. | | 502 | `installation_token_failed` | The broker couldn't mint a token for that repo. | | 502 | `sign_failed` | GitHub rejected the commit, commonly because `expected_head_oid` is stale. | | 503 | `sign_disabled` | `PROCESS_TRIGGER_SECRET` isn't set on this deployment. | ## GET /releases Latest release per repository, aggregated across the App's installations. It backs the private dashboard, not the action. **Auth:** `Authorization: Bearer `. ### Success `200 OK` ```json { "generated_at": "2026-08-20T09:00:00.000Z", "repos": [ { "repo": "MagmaMoose/diatreme", "latest": { "tag": "v2.4.6", "name": "v2.4.6", "published_at": "2026-08-20T01:15:00Z", "url": "https://github.com/MagmaMoose/diatreme/releases/tag/v2.4.6", "draft": false, "prerelease": false } } ], "truncated": false, "cached": true } ``` `latest` is `null` for a repository with no releases. `cached: true` means the response came from the KV cache rather than a fresh crawl. `truncated: true` means the aggregate hit a traversal cap, so the list is incomplete. The caps are in [Limits](limits.md#releases-aggregate). They are always reported, never applied silently. ### Failures | Status | `error` | When | | --- | --- | --- | | 401 | `unauthorized` | Bearer missing or wrong. | | 405 | `method_not_allowed` | Anything other than GET. | | 503 | `releases_disabled` | `PROCESS_TRIGGER_SECRET` isn't set. | | 503 | `app_unconfigured` | `GITHUB_APP_ID` or `GITHUB_APP_PRIVATE_KEY` isn't set. | ## POST /webhook Receiver for the Diatreme App's webhook deliveries. Only `push` is acted on: it fast-forwards every open pull request targeting the branch that was pushed, via GitHub's update-branch API. Every other event is acknowledged with `{ "ok": true, "ignored": "" }` so GitHub stops retrying it. **Auth:** HMAC-SHA256 over the raw body in `X-Hub-Signature-256`, checked against `GITHUB_WEBHOOK_SECRET`. The behaviour is opt-in twice over. Without `GITHUB_WEBHOOK_SECRET` the route returns `503 webhook_disabled`. With the secret but without `AUTO_UPDATE_BRANCHES` set to a true value, deliveries verify and then do nothing. | Status | `error` | When | | --- | --- | --- | | 400 | `invalid_json` / `invalid_request` | Malformed body. | | 401 | `invalid_signature` | HMAC didn't match. | | 405 | `method_not_allowed` | Anything other than POST. | | 503 | `webhook_disabled` | `GITHUB_WEBHOOK_SECRET` isn't set. | !!! note "The hosted App doesn't need this configured" Auto-update is off on the hosted deployment. If you self-host and want it, point the App's webhook at `/webhook` and set both secrets. ## Related - [Configuration](configuration.md) for every variable named above. - [Errors](errors.md) for what to do about each failure. - [Limits](limits.md) for caps, TTLs and lifetimes. --- # Broker configuration Source: docs/reference/configuration.md URL: https://docs.magmamoose.com/diatreme/reference/configuration/ Everything the broker reads at runtime. You only need this page if you self-host a broker or operate the hosted one. Consumers of the action configure nothing here: they set action inputs, which are documented in the [repository README](https://github.com/MagmaMoose/diatreme#inputs). All of these are read per request from the runtime environment, so changing one takes effect on the next request after a redeploy. None of them are read from a file at boot. On Cloudflare, secrets are set with `wrangler secret put ` and the KV namespaces are bound at deploy time. On AWS they come from SSM Parameter Store and the Lambda environment. See [Deployment](../operations/deployment.md). ## Required | Name | Type | Default | Secret | Effect | | --- | --- | --- | --- | --- | | `GITHUB_APP_ID` | string | none | no | Numeric App ID of the github.com GitHub App the broker acts as. Without it, `/token` and `/sign` cannot mint anything and `/releases` returns `503 app_unconfigured`. | | `GITHUB_APP_PRIVATE_KEY` | string (PEM) | none | yes | The App's private key. Accepts a real multi-line PEM or a single line with literal `\n` escapes. | ```text GITHUB_APP_ID= GITHUB_APP_PRIVATE_KEY= ``` ## Optional ### `OIDC_AUDIENCE` Comma-separated list of OIDC audiences `/token` accepts. Entries are trimmed and empties dropped. | | | | --- | --- | | Type | comma-separated string | | Default | `diatreme,release-runner` | | Secret | no | Blank or whitespace-only falls back to the default pair rather than accepting nothing. `release-runner` is the pre-rename audience, still accepted so long-pinned consumers keep working. A token whose `aud` isn't in the list fails with `401 invalid_oidc_token` and `reason: audience_mismatch`. The action sends whatever its `oidc-audience` input says, defaulting to `diatreme`. Change one without the other and every release in every repository pinned to that version breaks, so treat this list as append-only. ### `ALLOWED_REPOSITORIES` Comma-separated `owner/name` allowlist for `/token`. | | | | --- | --- | | Type | comma-separated string | | Default | unset, meaning every repository the App is installed on is allowed | | Secret | no | ```text ALLOWED_REPOSITORIES=MagmaMoose/diatreme,MagmaMoose/chargate ``` Matching is exact string equality after trimming. There's no globbing, so `MagmaMoose/*` matches nothing. A repository outside the list gets `403 repo_not_allowed`. ### `TOKEN_PERMISSIONS` Permissions stamped on the installation tokens `/token` mints. | | | | --- | --- | | Type | JSON object, or a comma-separated `key=value` / `key:value` list | | Default | `contents: write`, `pull_requests: write` | | Secret | no | ```text TOKEN_PERMISSIONS={"contents":"write","pull_requests":"write","packages":"write"} TOKEN_PERMISSIONS=contents=write,pull_requests=write ``` Keys must be lowercase with underscores, matching GitHub's App permission names. Values must be exactly `read` or `write`. Anything else, including a value of `admin` or an empty parse result, makes `/token` return `400 invalid_token_permissions` for every request. Blank or unset gives you the default pair. `/sign` ignores this and always mints with `contents: write` only. !!! warning "You cannot grant what the App doesn't have" This narrows or names permissions on the token. It can't exceed what the GitHub App itself was granted at install time. Asking for a permission the App lacks gets you a token without it, not an error. ### `PROCESS_TRIGGER_SECRET` Bearer token gating `POST /sign` and `GET /releases`. | | | | --- | --- | | Type | string | | Default | unset | | Secret | yes | Unset means both routes return `503` (`sign_disabled`, `releases_disabled`) and neither can be reached. Compared in constant time. The hosted broker sets it; a self-hosted broker that only needs `/token` can leave it out. ### `GITHUB_WEBHOOK_SECRET` HMAC-SHA256 secret for `POST /webhook`, matching the secret configured on the GitHub App. | | | | --- | --- | | Type | string | | Default | unset | | Secret | yes | Unset means `/webhook` returns `503 webhook_disabled`. ### `AUTO_UPDATE_BRANCHES` Enables the push auto-update behaviour behind `/webhook`. | | | | --- | --- | | Type | string flag | | Default | unset, disabled | | Secret | no | Enabled only by the exact values `1`, `true`, `yes` or `on`, case-insensitive after trimming. Every other value, including `enabled`, leaves it off. With it off, verified webhook deliveries are accepted and do nothing. ## GitHub Enterprise All five are opt-in and only meaningful together. Setting `GHE_OIDC_ISSUER` is what turns GHE support on: `/token` then trusts two issuers instead of one, and mints against whichever one actually signed the token. | Name | Required for GHE | Secret | Effect | | --- | --- | --- | --- | | `GHE_OIDC_ISSUER` | yes | no | The tenant's OIDC issuer, for example `https://token.actions.example.ghe.com`. Trailing slashes and stray whitespace are stripped. | | `GHE_API_BASE` | yes | no | The tenant's REST base, for example `https://example.ghe.com/api/v3`. | | `GHE_GITHUB_APP_ID` | yes | no | App ID of the duplicate App registered on the tenant. | | `GHE_GITHUB_APP_PRIVATE_KEY` | yes | yes | That App's private key. | | `GHE_GITHUB_APP_INSTALLATION_ID` | no | no | Skips the per-repo installation lookup, saving one API call. Ignored unless it parses to a positive integer. | A github.com token is still verified against github.com and minted with the github.com App. The issuer is pinned before its key set is selected, so a forged `iss` can't make the broker verify against the wrong tenant's keys. ## KV namespaces (Cloudflare only) Both are optional. Neither is hard-coded in `wrangler.jsonc`, so a self-hosted deploy without them still works. | Binding | Purpose | Without it | | --- | --- | --- | | `DIATREME_JWKS_CACHE` | Last-known-good JWKS snapshot per issuer, written after each successful verification. | The broker has no fallback when an issuer's key endpoint is unreachable, and returns `503 oidc_key_fetch_failed` instead of rescuing the request. | | `COPILOT_QUOTA_KV` | Caches the `GET /releases` aggregate. | `/releases` recomputes on every call. Nothing else changes. | Create and bind them: ```bash wrangler kv namespace create DIATREME_JWKS_CACHE wrangler kv namespace create COPILOT_QUOTA_KV ``` The deploy workflow injects the IDs from the `DIATREME_JWKS_CACHE_ID` and `COPILOT_QUOTA_KV_ID` Actions variables, so the namespace IDs never land in the repository. Set neither and the injection step is skipped entirely. !!! note "COPILOT_QUOTA_KV is a legacy name" The Copilot features that namespace was created for were removed. The binding name is kept because `env.COPILOT_QUOTA_KV` is what the code reads, and renaming it would orphan the cached data for no benefit. It has nothing to do with Copilot now. ## Local development Copy the example and fill it in: ```bash cp worker/.dev.vars.example worker/.dev.vars ``` `.dev.vars` is gitignored. `wrangler dev` reads it. The example file covers the App credentials and the GHE block; add any of the optional variables above by hand if you're working on those paths. ## Related - [Broker API](broker-api.md) for the routes these settings govern. - [Limits](limits.md) for the caps and TTLs that aren't configurable. --- # Errors Source: docs/reference/errors.md URL: https://docs.magmamoose.com/diatreme/reference/errors/ Every failure a Diatreme run can surface, what causes it, and what to do. The action fails hard: any broker fault exits the step non-zero, so a broken broker is a red X on the release rather than a silent skip. ## Reading a broker failure in the run log The action prints the HTTP status, the `error` code, the `reason` when there is one, and which broker answered: ```text Error: Token broker request failed with HTTP 401: invalid_oidc_token (audience_mismatch) [https://api.diatreme.magmamoose.com] ``` The hostname in brackets matters. If it's the fallback rather than the primary, the primary was unreachable or returned 5xx and you have two problems, not one. A preceding `::warning::` line names the primary's status. ## Token verification failures All of these are `401 invalid_oidc_token` unless noted. The `reason` is what tells you which check failed. | `reason` | What it means | What to do | | --- | --- | --- | | `malformed_token` | The value sent as `oidcToken` isn't a decodable JWT. | Almost always a broken OIDC mint upstream of the broker. Check the `Request public GitHub App token` step actually received a token, and that `id-token: write` is granted. | | `audience_mismatch` | The token's `aud` isn't in the broker's accepted list. | Your `oidc-audience` input and the broker's `OIDC_AUDIENCE` disagree. Leave the input at its default unless you run your own broker. | | `issuer_mismatch` | The token's `iss` isn't a trusted issuer. | Expected on a GitHub Enterprise runner talking to a broker without `GHE_OIDC_ISSUER` configured. See [Configuration](configuration.md#github-enterprise). | | `token_expired` | `exp` is in the past. | The token is minted seconds before use, so this means real clock skew or a job that stalled for an hour between mint and exchange. Re-run. | | `token_not_yet_valid` | `nbf` is in the future. | Clock skew on the broker side. Re-run, and if it persists, report it. | | `signature_invalid` | The signature didn't verify against a key that matched. | Not something a caller can cause with a genuine token. Report it. | | `kid_not_found` | No signing key matched the token's `kid`, even after a forced re-fetch. | Usually a GitHub key rotation the broker hasn't caught up with. Retry once. If it persists past a few minutes, report it. | | `key_ambiguous` | More than one key matched the `kid`. | Report it. Not caller-fixable. | | `alg_unsupported` | The token's algorithm isn't allowed. | Report it. | | `claim_invalid` | A claim other than `aud`, `iss` or `nbf` failed validation. | Report it with the run URL. | | `unknown` | The failure carried no classifiable code. | Report it with the run URL. | ### `403 repo_mismatch` The token's `repository` claim isn't the `owner`/`repo` the request asked for. The broker will not mint a token for a repository other than the one whose runner minted the OIDC token, which is the property that makes a public broker safe. Seeing this from an unmodified action means something rewrote the request. ### `403 repo_not_allowed` The repository is outside the broker's `ALLOWED_REPOSITORIES`. On a self-hosted broker, add it. On the hosted broker this shouldn't happen; report it. ### `404 app_not_installed` The Diatreme GitHub App isn't installed on the repository. Install it from [github.com/apps/diatreme](https://github.com/apps/diatreme) and re-run. This is the single most common first-run failure. ### `400 invalid_repository` `owner` or `repo` contains a character outside `A-Za-z0-9_.-`. Not reachable through the action, which derives both from `GITHUB_REPOSITORY`. ## Availability failures ### `503 oidc_key_fetch_failed` with `reason: jwks_unavailable` The broker could not retrieve the issuer's key set, so it never reached a verdict on your token. This is broker or upstream unavailability, not a bad token, and it is worth retrying. Causes seen in practice: a timeout or connection reset reaching `token.actions.githubusercontent.com`, a non-200 from that endpoint, or a response that doesn't parse as JSON. What to do: re-run the job. The broker keeps a last-known-good key set and will rescue the request from it when one is available and fresh enough, so a persistent 503 means both the live fetch and the snapshot are unusable. !!! note "Why this isn't a 401" It used to be. A bare catch turned every retrieval fault into `invalid_oidc_token`, which sent people hunting for a bad token during what was actually an outage, with no way to tell the two apart ([#147](https://github.com/MagmaMoose/diatreme/issues/147)). Retrieval faults are 503 now, and only 503. ### `500 github_installation_lookup_failed` GitHub answered the installation lookup with something the broker couldn't use. Transient. Re-run, and check [GitHub's status page](https://www.githubstatus.com/) if it repeats. ### `502 installation_token_failed` / `502 sign_failed` Only on `/sign`. The first means no token could be minted for that repository, the second that GitHub rejected the commit. The usual cause of `sign_failed` is a stale `expected_head_oid`: the branch moved between reading the head and writing the commit. Re-read the head and retry. ### `503 sign_disabled` / `503 releases_disabled` / `503 webhook_disabled` The relevant secret isn't configured on that deployment. See [Configuration](configuration.md). On a self-hosted broker this is your answer. On the hosted one, report it. ## Client-side action failures These come from the action's own scripts, before or instead of a broker call. | Message | Cause | Fix | | --- | --- | --- | | `auth-mode public-app requires token-broker-url.` | `token-broker-url` was explicitly set to an empty string. | Leave it unset to get the default, or give it a real URL. | | `OIDC request environment is unavailable. Grant 'id-token: write' to this job.` | The job has no OIDC permission, so no token can be minted at all. | Add `permissions: id-token: write` to the job. See [Setup](../setup.md#required-permissions). | | `GITHUB_REPOSITORY must be owner/repo.` | The environment variable is missing or malformed. | Only reachable outside a normal Actions run. | | `Token broker request failed with HTTP : ` | The broker answered non-200. | Find the `error` and `reason` in the tables above. | | `deploy-paths must be a JSON array of directories` | `deploy-paths` is not a JSON array of relative directories. Checked before anything is tagged. | Fix the value, e.g. `["k8s/overlays/acc", "k8s/overlays/prd"]`. | | `This push changes nothing but deploy-paths` | A deploy PR merged into a branch whose push trigger does not ignore those directories. Nothing was tagged. | Add them to the push trigger's `paths-ignore`. | ### `promote-from` refusals Every message in this table starts with `promote-from:`. All but the last stop the run before a tag, an image or a GitHub Release is written. | Message | Cause | Fix | | --- | --- | --- | | `tag '' does not exist in this repository` | The tag was mistyped, or never cut. The message lists the prereleases of that version that do exist. | Promote one of those. | | `'' is already a stable version` | A stable tag was passed. | Pass the prerelease, e.g. `v1.5.0-rc.3`. | | `'' is not a prerelease tag under tag-prefix ''` | The value is not a SemVer prerelease in this package's tag series. | Check `tag-prefix` matches the one the prerelease was cut with. | | `is a '' prerelease, but only '' prereleases are promoted to stable` | The tag is from a channel other than the one that feeds production: the environment before the last in `environments`. | Promote that channel's build, or correct `environments` and `prerelease-identifiers`. | | ` already exists on commit ` | A different build was already released as that stable version. | Cut a new version. If the tag was a mistake, delete it and its GitHub Release first. | | ` was already promoted from ` | Another prerelease on the same commit was already promoted to that version. It is a separate image, so promoting this one would repoint a published version. | Cut a new version. | | `was not cut by a promotion` | The stable version already exists on this commit and its tag has no `Promoted-From` line: an ordinary release cut it. | Nothing to promote; it is released. | | `cannot be combined with version-override` / `force-bump` | The version of a promotion is the source tag's own. | Remove the other input. | | `cannot be combined with publish-package and package-ecosystem: container` | That path runs `docker build` and would push a fresh image under the stable version. | Promote the image through a bake file or `Dockerfile`, or turn `publish-package` off for the run. | | `npm-provenance would attest the package to commit ` | The workflow was started on a commit other than the prerelease's, and npm attests to the workflow's commit. | Start the workflow from the prerelease tag, or turn `npm-provenance` off for the run. | | `a promotion always releases the stable version, to ''` | `environment` names something other than the last entry of `environments`. | Remove `environment`. | | `environments is not a JSON array` / `prerelease-identifiers is not a JSON object` | One of the two inputs does not parse. | Fix the JSON. | | `source image(s) are not in the registry` | The prerelease has a git tag but no image: its build failed, or a retention policy removed it. | Cut a new prerelease and promote that one. | | `could not retag as ` | The registry refused the retag after the stable tag was pushed. The message carries the registry's error. | Fix the cause and re-run. The promotion resumes from the tag that is already there; it never falls back to a rebuild. | Two more come from the tag push itself, without the prefix, when the remote already holds the stable tag and it is not this promotion's: | Message | Cause | Fix | | --- | --- | --- | | `Tag already exists on remote at , not at ` | Another run released a different build as that version between this run's checks and its push. | Cut a new version. | | `Tag already exists on remote on the commit being released, but it is not this release` | The tag on the remote does not record this prerelease as its source. | Cut a new version. | See [Promoting a release candidate to stable](../how-to/promote-a-release-candidate.md). ### `cut-release-branch` refusals Every message in this table starts with `cut-release-branch:`, and none of them leaves a branch behind. | Message | Cause | Fix | | --- | --- | --- | | `version-override is required` | The mode was run without a version. | Pass the version to cut, e.g. `1.4.0`. | | `'' carries a prerelease part` | A release branch is named after the release number only. | Pass `X.Y.Z`. The candidates cut from the branch get their `-rc.N` themselves. | | `'' is not a version` | The value is not `major.minor.patch`. | Fix the value. | | ` is already released` | That version shipped. | Pick the next version, or run on that line's latest tag to reopen it for a patch. | | ` is not above , the newest release` | A new release branch takes a higher version than anything released. | Pick a higher version, or reopen the older line from its latest tag. | | `release/ already exists on ` | A release branch is cut once. | Ship fixes to it through hotfix pull requests, or delete it first to start over. | | `could not create release/` | The token cannot create the branch: no `contents: write`, or a ruleset restricting `release/*` creation that the App cannot bypass. | Grant it, or add the App to the ruleset's bypass list. | | `could not check whether release/ exists` | The branch lookup failed with something other than "not found". | Usually transient or a token problem; the message carries the API error. | `release-branch-merge-back` and `release-branch-cleanup` never fail a release: everything that goes wrong after the release is out (a merge-back branch that cannot absorb a conflict, a branch a ruleset protects from deletion) is a warning naming the manual step. See [Releasing from release branches](../how-to/release-from-release-branches.md). ## Getting more detail On the Cloudflare deployment, every verification failure logs one structured line: ```bash npx wrangler tail diatreme --format json --search oidc_verify_failed ``` It carries the classified `reason`, the underlying error name and code, the token's `kid`, `iss`, `aud`, `repository`, `iat` and `exp`, the audiences and issuers the broker expected, and for a retrieval fault the upstream HTTP status and content type. It never carries the token itself. Field values are truncated, so a hostile token can't flood the log. ## Related - [Broker API](broker-api.md) for the full status table per route. - [Configuration](configuration.md) for the settings these errors point at. --- # Limits and lifetimes Source: docs/reference/limits.md URL: https://docs.magmamoose.com/diatreme/reference/limits/ Caps, timeouts and TTLs built into both broker implementations (Python/Lambda and TypeScript/Cloudflare Worker). None of these are configurable per request. They're here so you can tell a limit from a bug. ## Token lifetimes | Thing | Value | Set by | | --- | --- | --- | | Installation token returned by `/token` | GitHub's own lifetime, currently one hour | GitHub. The broker passes `expires_at` through and never computes it. | | App JWT used internally | 9 minutes, backdated 60 seconds | The broker, to absorb clock skew between it and GitHub. Never leaves the broker. | | OIDC token accepted by `/token` | Whatever the runner minted | GitHub Actions. | If you need a token to outlive a job, you don't: request a new one. Diatreme mints per run, not per repository. ## JWKS retrieval The key sets used to verify OIDC tokens. | Behaviour | Value | | --- | --- | | Cached key set is reused for | 5 minutes (jose's default is 10) | | Fetch timeout | 5 seconds | | Throttle between unmatched-key reloads | 30 seconds | | Minimum interval between forced reloads | 5 seconds | | Last-known-good snapshot is usable for | 24 hours | | Snapshot retention (Cloudflare Worker only) | 30 days | A token whose `kid` isn't in the cached set triggers one forced re-fetch, rate limited to once every 5 seconds across the whole broker. That's what recovers from a GitHub key rotation. When retrieval fails outright, verification falls back to the snapshot if one exists and is under 24 hours old. Past that age the snapshot is refused and the request gets `503 oidc_key_fetch_failed`, because serving from a key set that may have been rotated out is worse than failing loudly. !!! warning "Don't shorten the 30 second throttle" It looks like a knob for faster rotation recovery. It isn't. Lowering it widens the window in which jose's own unthrottled reload fires, and the result is more upstream fetches per rotation, not fewer. Recovery comes from the throttled explicit reload instead. ## Releases aggregate `GET /releases` walks the App's installations, so it's bounded to stay inside the platform's subrequest budget. | Cap | Value | | --- | --- | | Installations traversed | 10 | | Repositories per installation | 40 | | Cache TTL | 5 minutes | Hitting either cap sets `truncated: true` in the response. The list is never silently shortened. A `cached: true` response can be up to 5 minutes stale. ## Auto-update webhook | Cap | Value | | --- | --- | | Open pull requests updated per push | 100 | Only applies when `AUTO_UPDATE_BRANCHES` is enabled, which it isn't on the hosted deployment. ## Logging Every field in a structured log line is truncated to 128 characters. Tokens are never logged, in whole or in part, and neither is the underlying library's error message, which can embed claim values. ## Related - [Broker API](broker-api.md) - [Configuration](configuration.md) for the things that are configurable. --- # Security Source: docs/security.md URL: https://docs.magmamoose.com/diatreme/security/ Diatreme holds a GitHub App private key and mints short-lived, write-scoped installation tokens for other people's repositories. This page describes how it protects that, and what you're responsible for. To report a vulnerability, use [private vulnerability reporting](https://github.com/MagmaMoose/diatreme/security/advisories/new). Don't open a public issue. The full policy, scope and response targets are in [`SECURITY.md`](https://github.com/MagmaMoose/diatreme/blob/main/SECURITY.md). ## What stops one repository minting another's token `/token` takes an OIDC token and a repository. It mints only for the repository in the token's own `repository` claim: if the body asks for a different one, the request is refused with `403 repo_mismatch`. The claim comes from GitHub, not from the caller, so a repository cannot ask for a token it wasn't issued for. Verification pins the issuer before selecting its key set, so a token with a forged `iss` can't steer the broker into verifying against a different tenant's keys. Audience is checked against an explicit list. Expiry and not-before are enforced. Self-hosted deployments can narrow further with [`ALLOWED_REPOSITORIES`](reference/configuration.md#allowed_repositories). ## Token scope and lifetime Minted tokens carry `contents: write` and `pull_requests: write` by default, and are scoped to a single repository. They inherit GitHub's lifetime, currently one hour. A deployment can narrow the permission set with [`TOKEN_PERMISSIONS`](reference/configuration.md#token_permissions), but nothing can widen a token past what the App itself was granted at install time. The action masks the token with `::add-mask::` the moment it arrives, so it's redacted in the run log. ## Secret handling - The App private key, the bearer secret and the webhook secret live in the platform's secret store: - **Python/Lambda broker**: AWS SSM Parameter Store and Lambda environment. - **TypeScript Worker**: Cloudflare Secrets and environment (`.dev.vars` is gitignored; only `.dev.vars.example` with placeholders is tracked). - The bearer on `/sign` and `/releases` is compared in constant time. - `/webhook` verifies an HMAC-SHA256 over the raw request body before parsing it, so an unsigned payload is never interpreted. - Nothing logs a token, or any slice of one. Failure logs carry claim metadata and the classified reason, never the credential, and every field is truncated so a hostile token can't flood the log. ## Attack surface kept deliberately small The TypeScript Cloudflare Worker implementation keeps `workers_dev` and `preview_urls` off in `wrangler.jsonc`. Either would expose a second publicly reachable hostname for a live token minter, inheriting production secrets and bypassing the rules bound to the custom domain. The custom domain is the only intended door. (The production Python Lambda broker has equivalent controls at the API Gateway layer.) Repository owner and name are validated against `A-Za-z0-9_.-` before they're interpolated into any API URL. ## What you're responsible for **Pin by SHA for strict supply-chain reproducibility.** `@v2` is a floating tag this repository force-updates after every stable release, so it moves under you by design. `uses: MagmaMoose/diatreme@` doesn't. **Grant the job only the permissions it needs.** `id-token: write` is required for the OIDC exchange. `contents: write` and `pull-requests: write` are needed only for the modes that use them. See [Setup](setup.md#required-permissions). **Treat the broker hostname as part of your trust boundary.** Overriding `token-broker-url` points your OIDC tokens at someone else's server. Those tokens are short-lived and repository-scoped, but they are still credentials. Don't override it unless you run the broker. ## Supported versions | Version | Supported | | --- | --- | | `v2.x` | Yes | | `v1.x` and earlier | No, end of life. Move to `@v2`. | ## Related - [Broker API](reference/broker-api.md) for the auth model per route. - [Configuration](reference/configuration.md) for every secret the broker reads. --- # Setup Source: docs/setup.md URL: https://docs.magmamoose.com/diatreme/setup/ ## Use the action Pin to the floating major tag: ```yaml - uses: MagmaMoose/diatreme@v2 with: mode: release environment: prod ``` ### Required permissions The default `auth-mode: public-app` exchanges an Actions OIDC token for a short-lived GitHub App installation token through the hosted broker, so the job needs: ```yaml permissions: id-token: write # mint the OIDC token for the broker contents: write # create tags / releases pull-requests: write # promotion PRs / auto-merge ``` It also needs the hosted **[Diatreme GitHub App](https://github.com/apps/diatreme)** installed on the repository. Without it the first run fails with `404 app_not_installed`, which is the most common first-run failure. See the [repository README](https://github.com/MagmaMoose/diatreme#readme) for the full per-mode permission matrix and alternative auth modes (`github-token`, `app`). Add `attestations: write` as well if you turn on [image signing](action.md#signing-images-and-provenance). ### Verify it worked The release job's **Request public GitHub App token** step should end with: ```text Received short-lived public GitHub App token for /. ``` If it doesn't, the message names the HTTP status, an `error` code and often a `reason`. Look it up in [Errors](reference/errors.md). ## Local development This repo has two toolchains. Validate the surface you touched. ### Action surface (repo root) ```bash ruby -e 'require "yaml"; YAML.load_file("action.yml")' # parse metadata actionlint -color=false shellcheck -S warning scripts/*.sh bats tests/bats ``` !!! warning "macOS local bats quirk" Running `bats tests/bats` on macOS system Ruby (2.6) fails **only** `action-shell-syntax` because `YAML.safe_load_file` is unavailable there. That suite passes on CI, it is not a real failure. New shell scripts must be executable in Git (`core.fileMode` is off here): ```bash git update-index --chmod=+x scripts/.sh ``` ### Broker surface **Python broker** (`broker/`): ```bash pip install -r requirements-dev.txt pytest tests ``` **TypeScript Worker** (`worker/`) — the rollback target, kept deployable but not serving traffic: ```bash npm ci npm run typecheck # tsc --noEmit npm test # vitest npm run check # typecheck + tests + wrangler dry-run wrangler dev # run locally against .dev.vars ``` Copy `worker/.dev.vars.example` to `worker/.dev.vars` (gitignored) for local secrets. ## Build these docs ```bash pip install -r docs/requirements.txt mkdocs serve # preview at http://127.0.0.1:8000 mkdocs build --strict # render to ./site (gitignored) ``` `--strict` is what CI runs, so a broken internal link fails the build here the same way it fails the publish. --- # The broker Source: docs/worker.md URL: https://docs.magmamoose.com/diatreme/worker/ The GitHub App backend behind `https://api.diatreme.magmamoose.com`. It exists so callers don't have to register and run their own GitHub App: the action's default `auth-mode: public-app` exchanges an Actions OIDC token here for a short-lived installation token. ## Active implementation The production broker is a **Python/Lambda implementation** (`broker/app/`) running on AWS Lambda behind API Gateway in `eu-west-1`. The **TypeScript Cloudflare Worker** (`worker/src/index.ts`) remains in this repository as the code-of-record reference and rollback target, but is not currently serving any hostname. The two implementations use the same verification ladder and error contract, so the wire protocol is identical. For operations and deployment details, see [Deployment](operations/deployment.md). This page explains the shared broker concepts. The exhaustive tables live elsewhere so they can't drift apart: - [Broker API](reference/broker-api.md): every route, parameter and status code. - [Broker configuration](reference/configuration.md): every variable. - [Errors](reference/errors.md): every failure and its fix. - [Limits](reference/limits.md): caps, TTLs and lifetimes. ## Verification ladder Both broker implementations (Python/Lambda and TypeScript/Cloudflare Worker) follow the same verification order for `/token`, which is load-bearing: 1. Parse the body. Missing fields fail before any crypto runs. 2. Verify the OIDC token against the pinned issuer's key set. 3. Compare the token's `repository` claim to the requested `owner/repo`. 4. Check the deployment's repository allowlist. 5. Mint against the same GitHub host the token came from. Steps 3 and 4 come after verification because an unverified claim is worth nothing. Step 5 is what makes GitHub Enterprise work: a token from a configured GHE issuer mints through the GHE App against that tenant's REST base, and a github.com token never does. The full ladder and every status code is in [Broker API](reference/broker-api.md). ## Surviving a JWKS outage The broker can't verify anything without GitHub's public keys, so how it handles not having them is most of its reliability story. Two failure modes, handled differently: **A key rotation.** GitHub signs with a `kid` the cached key set doesn't contain. The library does not self-heal this on its own, so the broker forces one re-fetch, throttled to once every 5 seconds across the whole deployment. Don't "simplify" that throttle or the cooldown around it. Shortening the cooldown widens the window in which the library's own unthrottled reload fires and produces more upstream fetches per rotation, not fewer. **A retrieval fault.** The key endpoint times out, answers non-200, or returns something that isn't JSON. Every successful verification writes the key set to KV as a last-known-good snapshot, and a retrieval fault falls back to that snapshot rather than rejecting genuine tokens. The snapshot only ever supplies keys: every other claim check still runs against the real token, and a snapshot over 24 hours old is refused rather than trusted. With no usable snapshot the request gets `503 oidc_key_fetch_failed`, never a 401. That distinction is the whole point. A 401 says the broker reached a verdict and your token lost. A 503 says it never reached one. Collapsing the two turned an upstream outage into a permanent, unfalsifiable "bad token" ([#147](https://github.com/MagmaMoose/diatreme/issues/147)). ## Development and deployment Both broker implementations are kept in sync by their test suites: - **Python broker** (`broker/app/`) is production. Runs on AWS Lambda. Configuration via SSM Parameter Store and Lambda environment. Smoke-tested weekly against both broker hostnames. - **TypeScript Worker** (`worker/src/index.ts`) is the rollback target and code reference. Kept deployable but not serving traffic. Full deployment pipeline, secrets, rollback procedure, and smoke testing are in [Deployment](operations/deployment.md). Configuration options are documented in [Broker configuration](reference/configuration.md). ### Running locally (TypeScript Worker) If you need to verify the Worker locally: ```bash cd worker npm ci npm run typecheck # tsc --noEmit npm test # vitest npm run check # typecheck + tests + wrangler dry run wrangler dev # run locally against .dev.vars ``` Copy `worker/.dev.vars.example` to `worker/.dev.vars` and fill in the App credentials. The test suite covers routing, verification, and JWKS rotation separately.