Skip to content

ODP Releaser

ODP Releaser is a Python CLI tool and a set of GitHub Action workflows to help make deployment of Docker images to private repos more secure.

It takes advantage of GitHub's repository_dispatch event to communicate image changes to the private deployment repos, authenticated with a tightly scoped GitHub App owned by each deploy org.

sequenceDiagram
    participant Source as Source Repo
    participant Deploy as Deploy Repo

    Source->>Source: build + push image
    Source->>Deploy: repository_dispatch [image-published]
    Deploy->>Deploy: match image to image_manifest.yaml
    opt if image syncing configured
        Deploy->>Source: Sync images to new registry
    end
    Deploy->>Deploy: edit Kustomize/Helm/file manifests
    alt update_mode: commit
        Deploy->>Deploy: commit to main
    else update_mode: pr
        Deploy->>Deploy: open a pull request
    end
    opt if reporter app configured
        Deploy->>Source: deployment status + pull request comment
    end

In the source repos, a reusable notify workflow runs after images are built and pushed. It builds a client_payload and sends a repository_dispatch event to any number of deploy repos listed in the source repo's .github/deploy_targets.yaml.

The deploy repos have a reusable bump-images workflow triggered by that repository_dispatch event. It looks up the image against a local .github/image_manifest.yaml config to see what Kustomize, Helm, or other manifests need to be updated, checks the source repo against an optional allow-list, and either commits the change directly or opens a pull request.

Capabilities

  • Reporting back to the source repo. With a reporter GitHub App configured, bump-images reports each bump to the source repo as a GitHub deployment (shown on the source PR timeline and Environments sidebar), and a report-merged workflow flips a bump pull request's queued deployment to success once it merges.
  • Comments on the source pull request. If that app is additionally granted Pull requests: Read and write, each bump also comments on the source pull request — reading staged while a bump PR awaits review, and rewritten as deployed once it lands — from a built-in template that can be overridden per image or repo-wide.
  • Composite actions to build your own workflow. The reusable workflows are built from composite actions (install, bump_images, report_deployment, and comment_on_pr) that deploy repos can also use directly — including a stage_only mode that writes and stages the manifest changes without committing, so custom steps can run before the commit.
  • Deploying from and syncing to a mirrored registry. A deploy repo that pulls through a mirror rather than the upstream registry declares it with deployed_as, and can have odp-releaser actively copy the image there with sync: true.
  • Per-image authorization. Each image config can restrict which source repositories and which users/teams are allowed to bump it, independently of which source orgs the dispatch app trusts.
  • Offline validation. Both image_manifest.yaml and deploy_targets.yaml can be validated ahead of a release, without touching GitHub: via the odp-releaser validate CLI command, a shipped pre-commit hook, or the published JSON Schemas for editor and check-jsonschema support.

Where to go next

  • Getting started — install the CLI, understand the source/deployment repo split, and see the full end-to-end flow.
  • Source Repo — your repo builds and pushes container images, and should notify deploy repos about them.
  • Deployment Repo — your repo manages the Kubernetes, Kustomize, or Helm manifests that reference those images.
  • API — the composite actions, the CLI, the client_payload schema, and the GitHub Apps that authenticate everything.
  • Development — working on odp-releaser itself.