Action reference

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 inputs

MagmaMoose/diatreme@v2 — all 90 inputs are optional.

Input	Default	Description
mode	release	Pipeline mode. One of: ci Build Docker image and push pr-<N> to GHCR (run on pull_request events). 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). 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.
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:
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 <dockerfile> . — 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.<ghes-host>), 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-<N> 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 assembled pr-<N> image after build (mode: ci) and emit its SBOM + findings. 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.
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 <org>.
dependency-track-url	not set	Dependency-Track base URL (e.g. https://dtrack.example.com). When set, the image's CycloneDX SBOM is uploaded as the assembled-image project — distinct from any source-dependency SBOM project for the same repo. 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 image tag (e.g. pr-12).
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 Trivy findings report is imported. 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). 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. 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 <ecosystem>.HOSTNAME or data-residency <ecosystem>.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/&lt;owner&gt;/index.json. npm npm registry. Default https://registry.npmjs.org (public). maven Maven repo URL. Default https://maven.pkg.github.com/&lt;owner&gt;/&lt;repo&gt;. gradle Informational only — the repository is defined in build.gradle. rubygems Gem host. Default https://rubygems.pkg.github.com/&lt;owner&gt;. 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 <package-feed-url\|ghcr.io>/<package-name>:<version>. Defaults to the repository (owner/repo) lowercased. 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.
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 (plus the promote prefix). Add more via extra-branch-prefixes. 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.
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.
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 <version>-<identifier>.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: passed to gittools/actions@v4 as overrideConfig: increment=Major\|Minor\|Patch. 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.
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.
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).
images-promoted	Number of release image(s) retagged from a provenance-verified source image.
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.