Composite Actions

# Composite action: bump image references in the checked-out deploy repo.
#
# Runs `odp-releaser bump-images` against the incoming client_payload and the
# repo's image manifest config, then — depending on the image's update_mode —
# commits the change directly or opens a pull request. Set `stage_only: true`
# to instead write the manifest changes and `git add` them without committing,
# so the calling workflow can layer follow-up steps (e.g. syncing the image to
# another registry) on top of the staged bump before committing itself.
#
# Prerequisites:
#   - The deploy repo is checked out, with credentials that can push unless
#     stage_only is "true".
#   - Only when the image manifest asks for a sync (`deployed_as` with
#     `sync: true`): `skopeo` on the PATH — preinstalled on GitHub-hosted
#     ubuntu runners — and the destination registry already logged in to by
#     an earlier step (docker/login-action, or configure-aws-credentials +
#     amazon-ecr-login). skopeo reads those credentials from
#     $HOME/.docker/config.json via the containers credential search order,
#     so no separate `skopeo login` is needed. A caller that configures a
#     Docker *credential helper* instead is the exception — the credentials
#     are then not in that file, and skopeo won't resolve them.
#
# Minimal caller example:
#
#   - name: Bump images
#     id: bump
#     uses: gulfofmaine/odp-releaser/.github/actions/bump_images@<sha-or-tag>
#     # with:
#     #   stage_only: "true" # write + `git add` only; no commit, no PR

name: Bump images
description:
  Bump image references in deployment manifests, then commit, open a PR, or just
  stage the changes.

inputs:
  client_payload:
    description: >-
      repository_dispatch client_payload JSON produced by `odp-releaser notify`.
      Defaults to the payload of the workflow's triggering event.
    required: false
    default: ${{ toJSON(github.event.client_payload) }}
  config_path:
    description: Path to the image manifest config file.
    required: false
    default: .github/image_manifest.yaml
  verbosity:
    description: >-
      CLI verbosity: 0=warning, 1=info (default), 2 or more=debug. Maps to the
      CLI's -v/-vv/-vvv flags (capped at 3).
    required: false
    default: "1"
  git_user_name:
    description: Git author/committer name for direct commits.
    required: false
    default: odp-releaser[bot]
  git_user_email:
    description: Git author/committer email for direct commits.
    required: false
    default: odp-releaser[bot]@users.noreply.github.com
  stage_only:
    description: >-
      When "true", write the manifest changes and `git add` them, but make no
      commit and open no pull request, leaving follow-up steps to the caller.
      The image's update_mode is ignored.
    required: false
    default: "false"
  sync:
    description: >-
      When "false", skip the image sync even for configs whose `sync: true` asks
      for one. The sync otherwise runs whenever the image manifest declares a
      `deployed_as` with `sync: true`, before the bump is committed. Requires
      `skopeo` (preinstalled on GitHub-hosted ubuntu runners) and credentials
      for the destination registry already established by an earlier login step.
    required: false
    default: "true"
  dry_run: # group: Testing aids
    description: >-
      When "true", run the CLI with --dry-run (no manifest files written) and
      skip the stage, commit, and pull-request steps. Outputs are still
      produced. Testing aid; used by this repo's own e2e CI.
    required: false
    default: "false"
  token:
    description: >-
      Token used to push the bump commit or open the pull request. Pass an
      app-minted token if the resulting commit/PR should trigger CI. When the
      image manifest configures `team_reviewers`, the token also needs
      organization "Members: read" to request the team reviews — the
      bump-images.yml reusable workflow mints one automatically.
    required: false
    default: ${{ github.token }}
  reporter_apps: # group: Reporter app credentials
    description: >-
      Optional JSON object mapping source owner -> {app_id, private_key}
      reporter app credentials. Used (with organization "Members: read" granted
      to the app) to check `allowed_actors` team membership against source orgs.
    required: false
    default: ""
  reporter_app_id: # group: Reporter app credentials
    description: >-
      Optional App ID of the source org's reporter GitHub App, used to check
      `allowed_actors` team membership. Fallback for owners not in
      reporter_apps.
    required: false
    default: ""
  reporter_app_private_key: # group: Reporter app credentials
    description: Optional private key matching reporter_app_id.
    required: false
    default: ""

outputs:
  image_name:
    description: Image name the bump ran for (no tag or digest).
    value: ${{ steps.bump.outputs.image_name }}
  digest:
    description: Digest (sha256:...) of the image the bump ran for.
    value: ${{ steps.bump.outputs.digest }}
  new_tag:
    description:
      Tag the manifests were bumped to. For a release event this is the release
      ref, not the payload's `tag`, so prefer this over reading the client
      payload directly.
    value: ${{ steps.bump.outputs.new_tag }}
  changed:
    description: Whether any manifests changed ("true"/"false").
    value: ${{ steps.bump.outputs.changed }}
  update_mode:
    description:
      Update mode resolved from the image manifest config
      ("commit"/"pull_request").
    value: ${{ steps.bump.outputs.update_mode }}
  environment:
    description:
      GitHub environment name resolved from the image manifest config for
      deployment reporting; empty when unconfigured.
    value: ${{ steps.bump.outputs.environment }}
  environment_url:
    description:
      Deployment "View deployment" URL resolved (and templated) from the image
      manifest config; empty when unconfigured.
    value: ${{ steps.bump.outputs.environment_url }}
  pull_request_url:
    description:
      URL of the bump pull request; empty unless a pull_request-mode bump opened
      or updated one.
    value: ${{ steps.pr.outputs.pull-request-url }}
  branch_name:
    description: Branch name used for pull_request mode.
    value: ${{ steps.bump.outputs.branch_name }}
  commit_message:
    description: Generated commit message for the bump.
    value: ${{ steps.bump.outputs.commit_message }}
  pr_title:
    description: Generated pull request title for the bump.
    value: ${{ steps.bump.outputs.pr_title }}
  pr_body:
    description: >-
      Generated pull request body for the bump (includes the embedded report
      metadata).
    value: ${{ steps.bump.outputs.pr_body }}
  reviewers:
    description:
      Comma-separated GitHub usernames requested as reviewers on the bump pull
      request; empty when none are configured.
    value: ${{ steps.bump.outputs.reviewers }}
  team_reviewers:
    description:
      Comma-separated GitHub team slugs requested as reviewers on the bump pull
      request; empty when none are configured.
    value: ${{ steps.bump.outputs.team_reviewers }}
  comment_enabled:
    description:
      Whether commenting back on the source pull request is enabled for this
      image ("true"/"false").
    value: ${{ steps.bump.outputs.comment_enabled }}
  comment_pr_number:
    description:
      Source pull request the comment lands on; empty for events that carry no
      pull request (release, workflow_dispatch).
    value: ${{ steps.bump.outputs.comment_pr_number }}
  comment_staged_template:
    description:
      Resolved comment template for a bump pull request awaiting review,
      unrendered; pass to comment_on_pr.
    value: ${{ steps.bump.outputs.comment_staged_template }}
  comment_deployed_template:
    description: Resolved comment template for a landed bump, unrendered.
    value: ${{ steps.bump.outputs.comment_deployed_template }}
  sync_source_ref:
    description:
      Image reference the sync copies from, pinned by digest; empty when no
      config asked for a sync.
    value: ${{ steps.bump.outputs.sync_source_ref }}
  sync_destinations:
    description:
      Newline-separated destination references the image was (or would be)
      copied to; empty when no config asked for a sync.
    value: ${{ steps.bump.outputs.sync_destinations }}
  synced:
    description: >-
      Whether the sync step actually ran to completion ("true"/"false"). False
      when nothing was configured, the sync was skipped (sync: "false"), or this
      was a dry run.
    value: ${{ steps.sync.outputs.synced || 'false' }}

runs:
  using: composite
  steps:
    - name: Install ODP Releaser
      uses: $/.github/actions/install
      with:
        cache_suffix: odp-releaser-${{ github.action_ref }}

    - name: Bump images
      id: bump
      shell: bash
      env:
        IMAGE_MANIFEST_CONFIG_PATH: ${{ inputs.config_path }}
        CLIENT_PAYLOAD: ${{ inputs.client_payload }}
        VERBOSITY: ${{ inputs.verbosity }}
        DRY_RUN: ${{ inputs.dry_run }}
        # Only used to check `allowed_actors` team membership against the
        # source orgs; the CLI makes no other API calls here.
        REPORTER_APPS: ${{ inputs.reporter_apps }}
        REPORTER_APP_ID: ${{ inputs.reporter_app_id }}
        REPORTER_APP_PRIVATE_KEY: ${{ inputs.reporter_app_private_key }}
      run: |
        case "$VERBOSITY" in
          0) FLAGS=() ;;
          1) FLAGS=(-v) ;;
          2) FLAGS=(-vv) ;;
          *) FLAGS=(-vvv) ;;
        esac
        BUMP_ARGS=()
        if [ "$DRY_RUN" = "true" ]; then
          BUMP_ARGS+=(--dry-run)
        fi
        odp-releaser "${FLAGS[@]}" bump-images "${BUMP_ARGS[@]}"

    # Deliberately between the bump and every step that publishes it. A
    # merged manifest pointing at an image nobody pushed is an outage, so
    # unlike the deployment report and the source-PR comment (both
    # continue-on-error, both cosmetic) a failed sync has to fail the bump —
    # which only helps if it runs before the commit or pull request lands.
    - name: Sync image to the deploy registries
      id: sync
      if:
        inputs.dry_run != 'true' && inputs.sync != 'false' &&
        steps.bump.outputs.sync_destinations != ''
      shell: bash
      env:
        SOURCE_REF: ${{ steps.bump.outputs.sync_source_ref }}
        DESTINATIONS: ${{ steps.bump.outputs.sync_destinations }}
        EXPECTED_DIGEST: ${{ steps.bump.outputs.digest }}
      run: |
        set -euo pipefail

        if ! command -v skopeo >/dev/null; then
          echo "::error::skopeo not found on the PATH; it is preinstalled on" \
            "GitHub-hosted ubuntu runners, so a self-hosted runner needs it" \
            "installed to sync images to another registry"
          exit 1
        fi

        # A manifest's digest is the digest of its raw bytes, so this is exact
        # for a single image and for a multi-arch index alike. Plain `skopeo
        # inspect` has to resolve an index down to one platform before it can
        # parse it; --raw never does, so it can't disagree with the registry.
        manifest_digest() {
          skopeo inspect --raw "docker://$1" 2>/dev/null \
            | sha256sum | cut -d' ' -f1
        }

        while IFS= read -r destination; do
          [ -n "$destination" ] || continue

          # Skip a digest that is already there instead of re-pushing it.
          # Registries with tag immutability (ECR, and GHCR/Docker Hub with
          # immutability enabled) reject a re-push of the same tag, and a
          # re-dispatch of an already-mirrored digest is a legitimate no-op.
          # A destination that doesn't exist yet exits non-zero here, which
          # simply means "not there, copy it".
          if current="$(manifest_digest "$destination")" &&
            [ "sha256:$current" = "$EXPECTED_DIGEST" ]; then
            echo "$destination is already $EXPECTED_DIGEST; skipping"
            continue
          fi

          echo "Copying $SOURCE_REF to $destination"
          # --all is load-bearing, not belt-and-braces: without it skopeo
          # copies only the runner's own architecture, and --preserve-digests
          # does *not* object — it preserves that single image's digest
          # instead of the index's, landing a digest the manifests were never
          # bumped to. With --all, --preserve-digests fails loudly rather
          # than silently rewriting anything.
          # --retry-times because the default is 0: a single transient 5xx or
          # reset connection part-way through a multi-arch push would
          # otherwise fail the bump, and this step failing is deliberately
          # fatal. Retrying is the cheapest way to keep that strictness from
          # manufacturing outages out of blips.
          skopeo copy --all --preserve-digests --retry-times 3 \
            "docker://$SOURCE_REF" "docker://$destination"

          copied="$(manifest_digest "$destination")"
          if [ "sha256:$copied" != "$EXPECTED_DIGEST" ]; then
            echo "::error::$destination is sha256:$copied after the copy," \
              "but the manifests were bumped to $EXPECTED_DIGEST"
            exit 1
          fi
        done <<< "$DESTINATIONS"

        echo "synced=true" >> "$GITHUB_OUTPUT"

    - name: Stage bump
      if:
        inputs.dry_run != 'true' && inputs.stage_only == 'true' &&
        steps.bump.outputs.changed == 'true'
      shell: bash
      run: git add -A

    - name: Commit bump
      if:
        inputs.dry_run != 'true' && inputs.stage_only != 'true' &&
        steps.bump.outputs.changed == 'true' && steps.bump.outputs.update_mode
        == 'commit'
      shell: bash
      env:
        GIT_USER_NAME: ${{ inputs.git_user_name }}
        GIT_USER_EMAIL: ${{ inputs.git_user_email }}
        COMMIT_MESSAGE: ${{ steps.bump.outputs.commit_message }}
      run: |
        git config user.name "$GIT_USER_NAME"
        git config user.email "$GIT_USER_EMAIL"
        git add -A
        git commit -m "$COMMIT_MESSAGE"
        git push

    - name: Open bump pull request
      id: pr
      if:
        inputs.dry_run != 'true' && inputs.stage_only != 'true' &&
        steps.bump.outputs.changed == 'true' && steps.bump.outputs.update_mode
        == 'pull_request'
      uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1 # zizmor: ignore[superfluous-actions]
      with:
        token: ${{ inputs.token }}
        branch: ${{ steps.bump.outputs.branch_name }}
        commit-message: ${{ steps.bump.outputs.commit_message }}
        title: ${{ steps.bump.outputs.pr_title }}
        body: ${{ steps.bump.outputs.pr_body }}
        committer: ${{ inputs.git_user_name }} <${{ inputs.git_user_email }}>
        author: ${{ inputs.git_user_name }} <${{ inputs.git_user_email }}>
        delete-branch: true
        # Empty values are treated as "not provided" upstream, so these are
        # safe to pass unconditionally.
        reviewers: ${{ steps.bump.outputs.reviewers }}
        team-reviewers: ${{ steps.bump.outputs.team_reviewers }}

# Composite action: report a completed image bump back to the source repo.
#
# Runs `odp-releaser report-deployment`, which creates (or finds) a GitHub
# deployment on the *source* repository at the commit that built the image
# and sets its status: `success` for a bump committed directly, `queued` for
# a bump pull request that still needs review. Reporting is idempotent — an
# existing deployment for the same commit + environment has its status
# updated, which is how a merge-time run (`pr_body`) flips the bump PR's
# queued deployment to success.
#
# Provide exactly one of `client_payload` (right after a bump) or `pr_body`
# (after a bump pull request merged; the payload embedded at bump time is
# read back out of the body). A `pr_body` without embedded odp-releaser
# metadata is a friendly no-op, so it's safe to run on any closed PR.
#
# Prerequisites:
#   - Reporter app credentials for the source org — see the GitHub Apps docs.
#
# Minimal caller example:
#
#   - name: Report deployment
#     uses: gulfofmaine/odp-releaser/.github/actions/report_deployment@<sha-or-tag>
#     with:
#       update_mode: ${{ steps.bump.outputs.update_mode }}
#       reporter_app_id: ${{ secrets.REPORTER_APP_ID }}
#       reporter_app_private_key: ${{ secrets.REPORTER_APP_PRIVATE_KEY }}

name: Report deployment
description:
  Report a completed image bump back to the source repo as a GitHub deployment
  and status.

inputs:
  client_payload:
    description: >-
      repository_dispatch client_payload JSON produced by `odp-releaser notify`.
      Provide either this or pr_body.
    required: false
    default: ""
  pr_body:
    description: >-
      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 client_payload. A body without embedded metadata is a no-op.
    required: false
    default: ""
  update_mode:
    description: >-
      How the bump landed ("commit" reports a success deployment, "pull_request"
      reports a queued one).
    required: false
    default: commit
  environment:
    description: >-
      GitHub environment name for the deployment. An environment embedded in
      pr_body wins; empty falls back to the deploy repo's owner/name slug.
    required: false
    default: ""
  environment_url:
    description: >-
      "View deployment" link for the deployment status — typically the bump
      commit or pull request URL. A URL embedded in pr_body wins.
    required: false
    default: ""
  verbosity:
    description: >-
      CLI verbosity: 0=warning, 1=info (default), 2 or more=debug. Maps to the
      CLI's -v/-vv/-vvv flags (capped at 3).
    required: false
    default: "1"
  reporter_apps: # group: Reporter app credentials
    description: >-
      JSON object mapping source owner -> {app_id, private_key} reporter app
      credentials, for deploy repos that report to multiple source orgs.
    required: false
    default: ""
  reporter_app_id: # group: Reporter app credentials
    description: >-
      App ID of the reporter GitHub App installed on the source repos.
    required: false
    default: ""
  reporter_app_private_key: # group: Reporter app credentials
    description: Private key matching reporter_app_id.
    required: false
    default: ""

runs:
  using: composite
  steps:
    - name: Install ODP Releaser
      uses: $/.github/actions/install
      with:
        cache_suffix: odp-releaser-${{ github.action_ref }}

    - name: Report deployment
      shell: bash
      env:
        CLIENT_PAYLOAD: ${{ inputs.client_payload }}
        PR_BODY: ${{ inputs.pr_body }}
        UPDATE_MODE: ${{ inputs.update_mode }}
        ENVIRONMENT: ${{ inputs.environment }}
        ENVIRONMENT_URL: ${{ inputs.environment_url }}
        VERBOSITY: ${{ inputs.verbosity }}
        REPORTER_APPS: ${{ inputs.reporter_apps }}
        REPORTER_APP_ID: ${{ inputs.reporter_app_id }}
        REPORTER_APP_PRIVATE_KEY: ${{ inputs.reporter_app_private_key }}
      run: |
        case "$VERBOSITY" in
          0) FLAGS=() ;;
          1) FLAGS=(-v) ;;
          2) FLAGS=(-vv) ;;
          *) FLAGS=(-vvv) ;;
        esac
        odp-releaser "${FLAGS[@]}" report-deployment

# Composite action: comment on the source pull request about a bump.
#
# Runs `odp-releaser comment`, which posts (or updates) a markdown comment on
# the *source* repository's pull request saying which image was bumped and
# where. A `pull_request`-mode bump posts the `staged` comment — nothing is
# live until the bump pull request merges — and a landed bump posts the
# `deployed` one. Reruns update the same comment rather than adding another:
# it's found by an invisible marker keyed on this deploy repo, the image, and
# the environment, so other deploy repos' comments are never touched.
#
# Provide exactly one of `client_payload` (right after a bump) or `pr_body`
# (after a bump pull request merged; the templates, environment and source pull
# request number embedded at bump time are read back out of the body). A
# `pr_body` without embedded odp-releaser metadata is a friendly no-op, so it's
# safe to run on any closed PR.
#
# Prerequisites:
#   - Reporter app credentials for the source org, whose app has been granted
#     `Pull requests: Read and write` — and whose existing installations have
#     accepted that permission. See the GitHub Apps docs.
#
# Minimal caller example:
#
#   - name: Comment on the source pull request
#     uses: gulfofmaine/odp-releaser/.github/actions/comment_on_pr@<sha-or-tag>
#     with:
#       update_mode: ${{ steps.bump.outputs.update_mode }}
#       staged_template: ${{ steps.bump.outputs.comment_staged_template }}
#       deployed_template: ${{ steps.bump.outputs.comment_deployed_template }}
#       reporter_app_id: ${{ secrets.REPORTER_APP_ID }}
#       reporter_app_private_key: ${{ secrets.REPORTER_APP_PRIVATE_KEY }}

name: Comment on source pull request
description:
  Comment on the source repository's pull request saying where an image was
  deployed.

inputs:
  client_payload:
    description: >-
      repository_dispatch client_payload JSON produced by `odp-releaser notify`.
      Provide either this or pr_body.
    required: false
    default: ""
  pr_body:
    description: >-
      Body of a merged bump pull request; the payload, environment, comment
      templates and source pull request number embedded at bump time are read
      from it. Provide either this or client_payload. A body without embedded
      metadata is a no-op.
    required: false
    default: ""
  update_mode:
    description: >-
      How the bump landed ("commit" posts the deployed comment, "pull_request"
      posts the staged one).
    required: false
    default: commit
  environment:
    description: >-
      GitHub environment name named in the comment, and part of the comment's
      identity. An environment embedded in pr_body wins; empty falls back to the
      deploy repo's owner/name slug.
    required: false
    default: ""
  environment_url:
    description: >-
      Available to templates as `{environment_url}`. An URL embedded in pr_body
      wins; empty falls back to bump_url.
    required: false
    default: ""
  bump_url:
    description: >-
      Where the bump itself lives — the bump commit or pull request URL —
      available to templates as `{bump_url}`.
    required: false
    default: ""
  run_url:
    description: >-
      Available to templates as `{run_url}`. Empty (the default) uses this
      workflow run, which is normally what you want; set it to point a comment
      at a different run — e.g. the job that actually deployed, when the bump is
      one step of a longer pipeline.
    required: false
    default: ""
  pr_number:
    description: >-
      Source pull request to comment on (the `comment_pr_number` output of
      `bump-images`). Empty falls back to the payload's own pull request; no
      pull request at all is a no-op.
    required: false
    default: ""
  comment_enabled:
    description: >-
      Whether to comment at all (the `comment_enabled` output of `bump-images`).
      "false" is a no-op.
    required: false
    default: "true"
  staged_template:
    description: >-
      Comment body used for a `pull_request`-mode bump (the
      `comment_staged_template` output of `bump-images`). A template embedded in
      pr_body wins.
    required: false
    default: ""
  deployed_template:
    description: >-
      Comment body used once the bump has landed (the
      `comment_deployed_template` output of `bump-images`). A template embedded
      in pr_body wins.
    required: false
    default: ""
  verbosity:
    description: >-
      CLI verbosity: 0=warning, 1=info (default), 2 or more=debug. Maps to the
      CLI's -v/-vv/-vvv flags (capped at 3).
    required: false
    default: "1"
  reporter_apps: # group: Reporter app credentials
    description: >-
      JSON object mapping source owner -> {app_id, private_key} reporter app
      credentials, for deploy repos that report to multiple source orgs.
    required: false
    default: ""
  reporter_app_id: # group: Reporter app credentials
    description: >-
      App ID of the reporter GitHub App installed on the source repos. It must
      be granted `Pull requests: Read and write` for commenting.
    required: false
    default: ""
  reporter_app_private_key: # group: Reporter app credentials
    description: Private key matching reporter_app_id.
    required: false
    default: ""

runs:
  using: composite
  steps:
    - name: Install ODP Releaser
      uses: $/.github/actions/install
      with:
        cache_suffix: odp-releaser-${{ github.action_ref }}

    - name: Comment on source pull request
      shell: bash
      env:
        CLIENT_PAYLOAD: ${{ inputs.client_payload }}
        PR_BODY: ${{ inputs.pr_body }}
        UPDATE_MODE: ${{ inputs.update_mode }}
        ENVIRONMENT: ${{ inputs.environment }}
        ENVIRONMENT_URL: ${{ inputs.environment_url }}
        BUMP_URL: ${{ inputs.bump_url }}
        RUN_URL: ${{ inputs.run_url }}
        COMMENT_PR_NUMBER: ${{ inputs.pr_number }}
        COMMENT_ENABLED: ${{ inputs.comment_enabled }}
        COMMENT_STAGED_TEMPLATE: ${{ inputs.staged_template }}
        COMMENT_DEPLOYED_TEMPLATE: ${{ inputs.deployed_template }}
        VERBOSITY: ${{ inputs.verbosity }}
        REPORTER_APPS: ${{ inputs.reporter_apps }}
        REPORTER_APP_ID: ${{ inputs.reporter_app_id }}
        REPORTER_APP_PRIVATE_KEY: ${{ inputs.reporter_app_private_key }}
      run: |
        case "$VERBOSITY" in
          0) FLAGS=() ;;
          1) FLAGS=(-v) ;;
          2) FLAGS=(-vv) ;;
          *) FLAGS=(-vvv) ;;
        esac
        odp-releaser "${FLAGS[@]}" comment