CLI
The workflows use the CLI behind the scene, but odp-releaser can also be used to validate and test the effects of workflows.
Usage: odp-releaser [OPTIONS] COMMAND [ARGS]...
Tooling to help manage releasing Docker images across repos
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --verbose -v <int range> [0<=x<=3] Increase verbosity of logging │
│ [default: 0] │
│ --version -V Show version │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ notify Dispatch the published image to every configured deploy │
│ target. │
│ bump-images Update the deployment with the given manifest config and │
│ client payload. │
│ report-deployment Report a completed bump to the source repo as a GitHub │
│ deployment. │
│ comment Comment on the source pull request saying where an image │
│ was deployed. │
│ generate-config Generate configuration files for ODP Releaser │
│ validate Validate odp-releaser configs statically, without │
│ touching GitHub │
│ test Validate configs by mock running `notify` or │
│ `bump-images`. │
╰──────────────────────────────────────────────────────────────────────────────╯
odp-releaser
Tooling to help manage releasing Docker images across repos
Usage
odp-releaser [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
| Name | Description | Required | Default |
|---|---|---|---|
-v, --verbose |
Increase verbosity of logging | No | 0 |
-V, --version |
Show version | No | False |
Commands
| Name | Description |
|---|---|
notify |
Dispatch the published image to every... |
bump-images |
Update the deployment with the given... |
report-deployment |
Report a completed bump to the source repo... |
comment |
Comment on the source pull request saying... |
completion |
Generate and install completion scripts. |
generate-config |
Generate configuration files for ODP Releaser |
validate |
Validate odp-releaser configs statically,... |
test |
Validate configs by mock running notify... |
Subcommands
notify
Dispatch the published image to every configured deploy target.
Builds the client_payload from the GitHub Actions environment (the same
payload make-payload prints), reads the deploy targets, and sends a
repository_dispatch event to each one. All targets are attempted even
if an earlier one fails, a Markdown summary is always written to the GitHub
step summary, and the command exits non-zero if any target failed.
With --dry-run credentials are resolved for each target but no tokens
are minted and no dispatch events are sent.
Writes the per-target outcomes to GITHUB_OUTPUT as a results JSON
array of {owner, repo, event_type, ok, detail} objects plus a
target_count, so callers (including this repo's own e2e CI) can assert
on what happened instead of only on the exit code.
Usage
odp-releaser notify [OPTIONS] {image_name} {tag} {digest}
Arguments
| Name | Description | Required |
|---|---|---|
image_name |
Name of the published image | Yes |
tag |
Tag applied to the published image | Yes |
digest |
Content digest of the published image | Yes |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--github-event-name |
Name of the GitHub event | Yes | - |
--github-event-path |
Path to the event payload JSON | Yes | - |
--github-repository |
owner/name of the repo |
Yes | - |
--github-actor |
User who triggered the event | Yes | - |
--github-run-id |
ID of the workflow run | Yes | - |
--github-ref-name |
Name of the ref | Yes | - |
--github-sha |
Git SHA of the commit | Yes | - |
--github-token |
Token used to look up the pull request associated with a pushed commit. Without it, push events are dispatched with a null pr. | No | - |
--github-server-url |
Base URL of the GitHub server | No | https://github.com |
--targets-path |
Path to the deploy targets YAML file | No | .github/deploy_targets.yaml |
--dry-run |
Resolve credentials for each target but send no dispatch events | No | False |
bump-images
Update the deployment with the given manifest config and client payload.
Usage
odp-releaser bump-images [OPTIONS] {client_payload}
Arguments
| Name | Description | Required |
|---|---|---|
client_payload |
repository_dispatch client_payload string, can be loaded from env: CLIENT_PAYLOAD |
Yes |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--config-path |
Path to the image manifest configuration file. Paths inside the config (manifest paths) are resolved relative to this file's parent directory. | No | .github/image_manifest.yaml |
--dry-run / --no-dry-run |
Template the changes, but don't write them | No | no-dry-run |
report-deployment
Report a completed bump to the source repo as a GitHub deployment.
Creates a deployment on the source repository (from the payload's repo
and git_sha) and sets its status: success for a direct commit,
queued for a bump pull request that still needs review. An existing
deployment for the same commit and environment is reused, so running
again after the bump PR merges flips its status instead of duplicating
it. Requires reporter app credentials in the environment.
Usage
odp-releaser report-deployment [OPTIONS][client_payload]
Arguments
| Name | Description | Required |
|---|---|---|
client_payload |
repository_dispatch client_payload string, can be loaded from env: CLIENT_PAYLOAD. Provide either this or --pr-body. |
No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--github-repository |
owner/name of the repo |
Yes | - |
--github-run-id |
ID of the workflow run | Yes | - |
--github-server-url |
Base URL of the GitHub server | No | https://github.com |
--pr-body |
Body of a merged bump pull request; the payload, environment and environment URL embedded at bump time are read from it. Provide either this or the client payload. | No | - |
--update-mode [commit|pull_request] |
How the bump landed (the update_mode output of bump-images): commit reports a success deployment, pull_request reports a queued one |
No | commit |
--environment |
GitHub environment name for the deployment. An environment embedded in --pr-body wins; unset falls back to the deploy repo's owner/name slug | No | - |
--environment-url |
Shown as the 'View deployment' link on the source repo — typically the bump commit or pull request URL. An URL embedded in --pr-body wins. | No | - |
comment
Comment on the source pull request saying where an image was deployed.
Posts the staged comment for a bump pull request awaiting review and the
deployed one once the bump has landed, updating this deploy repo's
existing comment for the image rather than adding another. Requires
reporter app credentials with Pull requests: Read and write.
Usage
odp-releaser comment [OPTIONS][client_payload]
Arguments
| Name | Description | Required |
|---|---|---|
client_payload |
repository_dispatch client_payload string, can be loaded from env: CLIENT_PAYLOAD. Provide either this or --pr-body. |
No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--github-repository |
owner/name of the repo |
Yes | - |
--pr-body |
Body of a merged bump pull request; the payload, environment and comment templates embedded at bump time are read from it. Provide either this or the client payload. | No | - |
--update-mode [commit|pull_request] |
How the bump landed (the update_mode output of bump-images): commit posts the deployed comment, pull_request posts the staged one |
No | commit |
--environment |
GitHub environment name named in the comment, and part of the comment's identity. An environment embedded in --pr-body wins; unset falls back to the deploy repo's owner/name slug | No | - |
--environment-url |
Available to templates as {environment_url}. An URL embedded in --pr-body wins; unset falls back to --bump-url |
No | - |
--bump-url |
Where the bump itself lives — the bump commit or pull request URL — available to templates as {bump_url} |
No | - |
--run-url |
This workflow run's URL, available to templates as {run_url}; defaults to the run the CLI is executing in |
No | - |
--pr-number |
Source pull request to comment on (the comment_pr_number output of bump-images). Unset falls back to the payload's own pull request; no pull request at all is a no-op |
No | - |
--comment-enabled / --no-comment-enabled |
Whether to comment at all (the comment_enabled output of bump-images). False is a no-op |
No | comment-enabled |
--staged-template |
Comment body used for a pull_request-mode bump (the comment_staged_template output of bump-images). A template embedded in --pr-body wins |
No | - |
--deployed-template |
Comment body used once the bump has landed (the comment_deployed_template output of bump-images). A template embedded in --pr-body wins |
No | - |
--github-server-url |
Base URL of the GitHub server | No | https://github.com |
--github-run-id |
ID of the workflow run | No | - |
completion
Generate and install completion scripts.
Usage
odp-releaser completion [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
No options available
Subcommands
show
Show completion for the specified shell, to copy or customize it.
Usage
odp-releaser completion show [OPTIONS]
Arguments
| Name | Description | Required |
|---|---|---|
shell |
Yes |
Options
No options available
install
Install completion for the specified shell.
Usage
odp-releaser completion install [OPTIONS]
Arguments
| Name | Description | Required |
|---|---|---|
shell |
Yes |
Options
No options available
generate-config
Generate configuration files for ODP Releaser
Usage
odp-releaser generate-config [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
No options available
Subcommands
image-manifest
Generate an image_manifest.yaml configuration file for deploy repo to call with odp-releaser bump-images.
Usage
odp-releaser generate-config image-manifest [OPTIONS]
Arguments
No arguments available
Options
No options available
deploy-targets
Generate a deploy_targets.yaml configuration for a source repo to call with odp-releaser notify.
Usage
odp-releaser generate-config deploy-targets [OPTIONS]
Arguments
No arguments available
Options
No options available
schema
Generate JSON Schemas for ODP Releaser configuration files
Usage
odp-releaser generate-config schema [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
No options available
validate
Validate odp-releaser configs statically, without touching GitHub
Usage
odp-releaser validate [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
No options available
Subcommands
image-manifest
Validate one or more image_manifest.yaml configs.
Defaults to checking .github/image_manifest.yaml when no paths are
given. Exits 1 if any file has errors (or, with --strict, any
warnings).
Usage
odp-releaser validate image-manifest [OPTIONS][paths]...
Arguments
| Name | Description | Required |
|---|---|---|
paths |
image_manifest.yaml paths to validate. Defaults to .github/image_manifest.yaml when omitted; a pre-commit hook appends the matched filenames here instead. | No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--strict |
Also fail (exit 1) on warning-only results, not just errors | No | False |
--no-check-files |
Skip filesystem checks on manifests an image_manifest.yaml references, for a repo whose manifests live outside this checkout | No | False |
deploy-targets
Validate one or more deploy_targets.yaml configs.
Defaults to checking .github/deploy_targets.yaml when no paths are
given. Exits 1 if any file has errors (or, with --strict, any
warnings).
Usage
odp-releaser validate deploy-targets [OPTIONS][paths]...
Arguments
| Name | Description | Required |
|---|---|---|
paths |
deploy_targets.yaml paths to validate. Defaults to .github/deploy_targets.yaml when omitted; a pre-commit hook appends the matched filenames here instead. | No |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--strict |
Also fail (exit 1) on warning-only results, not just errors | No | False |
test
Validate configs by mock running notify or bump-images.
Usage
odp-releaser test [OPTIONS] COMMAND [ARGS]...
Arguments
No arguments available
Options
No options available
Subcommands
notify
Validate deploy targets and dispatch-credential availability.
Builds a canned client_payload for the chosen event type (the same
payloads test bump-images uses), reads the deploy targets, and reports,
per target, whether dispatch app credentials are available. No tokens are
minted and no network calls are made; this only checks whether
DISPATCH_APP_ID/DISPATCH_APP_PRIVATE_KEY or DISPATCH_APPS cover
every configured target owner.
Missing credentials for a target are reported, not treated as a failure:
the command exits non-zero only when targets_path does not exist, is
empty, or fails to parse as a valid deploy-targets file.
Usage
odp-releaser test notify [OPTIONS]
Arguments
No arguments available
Options
| Name | Description | Required | Default |
|---|---|---|---|
--targets-path |
Path to the deploy targets YAML file | No | .github/deploy_targets.yaml |
--image-name |
Name of the image to substitute into the canned client payload. Prompted interactively when omitted. | No | - |
--event-type [push|release|workflow_dispatch] |
Canned client_payload event to load: push, release, or workflow_dispatch. Prompted interactively when omitted. | No | - |
bump-images
Test bumping images with the given configuration, image name, and event type.
Runs bump-images in dry-run mode against a canned client_payload for
the chosen event type, with the image name substituted in. Any of
--config-path, --image-name, or --event-type left unset is prompted
for interactively, so pass all three explicitly to run this non-interactively
(e.g. in CI).
Usage
odp-releaser test bump-images [OPTIONS]
Arguments
No arguments available
Options
| Name | Description | Required | Default |
|---|---|---|---|
--config-path |
Path to the image_manifest.yaml config to test against. Prompted interactively when omitted. | No | - |
--image-name |
Name of the image to substitute into the canned client payload. Prompted interactively when omitted, listing the config's configured image names once the config path is known. | No | - |
--event-type [push|release|workflow_dispatch] |
Canned client_payload event to load: push, release, or workflow_dispatch. Prompted interactively when omitted. | No | - |
make-payload
Make a client payload for a repository_dispatch call for the given image and GitHub context.
Reads the event JSON from GITHUB_EVENT_PATH when it's needed to build
the payload (currently only for release events); push and
workflow_dispatch events don't read it, so a missing or absent event
file is fine for those. Prints payload.model_dump_json() to stdout so
a workflow step can capture it, e.g. into CLIENT_PAYLOAD or straight
into a gh api ... /dispatches call. All other logging goes to
stderr.
Usage
odp-releaser test make-payload [OPTIONS] {image_name} {tag} {digest}
Arguments
| Name | Description | Required |
|---|---|---|
image_name |
Name of the published image | Yes |
tag |
Tag applied to the published image | Yes |
digest |
Content digest of the published image | Yes |
Options
| Name | Description | Required | Default |
|---|---|---|---|
--github-event-name |
Name of the GitHub event | Yes | - |
--github-event-path |
Path to the event payload JSON | Yes | - |
--github-repository |
owner/name of the repo |
Yes | - |
--github-actor |
User who triggered the event | Yes | - |
--github-run-id |
ID of the workflow run | Yes | - |
--github-ref-name |
Name of the ref | Yes | - |
--github-sha |
Git SHA of the commit | Yes | - |
--github-token |
Token used to look up the pull request associated with a pushed commit. Without it, push events are dispatched with a null pr. | No | - |
--github-server-url |
Base URL of the GitHub server | No | https://github.com |