Bump images workflow

# Reusable workflow: bump image references in a deploy repo.
#
# This workflow is meant to be called by a deploy repo in response to a
# repository_dispatch event sent by `odp-releaser notify`. It runs the
# `bump_images` composite action from this repo (resolved at the same commit
# as this workflow file), which reads the incoming client_payload and
# this repo's image manifest, then either commits the bump directly or opens
# a pull request with the updated image references.
#
# When the deploy org's own dispatch-app credentials are supplied (via the
# ci_app_id / ci_app_private_key secrets), the commit/PR is authored with an
# app-minted token so the resulting change triggers this repo's own CI.
# Pushes/PRs authored with the default GITHUB_TOKEN do not trigger further
# workflow runs by GitHub Actions design.
#
# When the source org's reporter-app credentials are supplied (via the
# reporter_app_id / reporter_app_private_key secrets), a successful bump is
# also reported back to the source repo as a GitHub deployment + status, so
# the source PR timeline and Environments sidebar show where the image went.
# If that app has additionally been granted `Pull requests: Read and write`,
# the bump also comments on the source pull request — `staged` while a bump PR
# awaits review, `deployed` once it lands. Both reports are best effort and
# never fail the bump.
#
# When an image manifest declares a `deployed_as` with `sync: true`, the image
# is also copied to that registry before the bump is committed. Supply
# credentials for the destination either with the sync_aws_role_arn /
# sync_aws_region inputs (ECR via OIDC) or the sync_registry / sync_username /
# sync_password secrets (GHCR, Docker Hub). A failed copy fails the bump, on
# purpose: a merged manifest pointing at an image nobody pushed is an outage.
#
# UPGRADING: this workflow now requests `id-token: write`, which is never
# granted by default, and a called workflow's permissions can only be
# maintained or reduced relative to its caller -- never elevated. So every
# calling job must now grant it, even one that never syncs:
#
#   permissions:
#     contents: write
#     pull-requests: write
#     id-token: write   # <- add this
#
# Minimal caller example:
#
#   on:
#     repository_dispatch:
#       types: [image-published]
#
#   jobs:
#     bump:
#       permissions:
#         contents: write
#         pull-requests: write
#         id-token: write
#       uses: gulfofmaine/odp-releaser/.github/workflows/bump-images.yml@<ref>
#       with:
#         # config_path: .github/image_manifest.yaml            # optional
#         # git_user_name: odp-releaser[bot]                    # optional
#         # git_user_email: odp-releaser[bot]@users.noreply.github.com
#         # verbosity: 1                                       # optional, default
#       secrets:
#         ci_app_id: ${{ secrets.CI_APP_ID }}                   # optional
#         ci_app_private_key: ${{ secrets.CI_APP_PRIVATE_KEY }} # optional
#         reporter_apps: ${{ secrets.REPORTER_APPS }}           # optional
#         reporter_app_id: ${{ secrets.REPORTER_APP_ID }}       # optional
#         reporter_app_private_key: ${{ secrets.REPORTER_APP_PRIVATE_KEY }} # optional

name: Bump images

on:
  workflow_call:
    inputs:
      config_path:
        description: Path to the image manifest config file.
        required: false
        type: string
        default: .github/image_manifest.yaml
      git_user_name:
        description: Git author/committer name for direct commits.
        required: false
        type: string
        default: odp-releaser[bot]
      git_user_email:
        description: Git author/committer email for direct commits.
        required: false
        type: string
        default: odp-releaser[bot]@users.noreply.github.com
      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
        type: number
        default: 1
      client_payload: # group: Testing aids
        description: >-
          Explicit client_payload JSON string. Empty (the default) uses the
          triggering repository_dispatch event's client_payload. Testing aid for
          calling this workflow outside a repository_dispatch run.
        required: false
        type: string
        default: ""
      dry_run: # group: Testing aids
        description: >-
          Run the CLI with --dry-run (no manifest files written) and skip the
          commit and pull-request steps. Outputs are still produced. Testing
          aid; used by this repo's own e2e CI.
        required: false
        type: boolean
        default: false
      sync: # group: Image sync
        description: >-
          Set false to skip the image sync even for configs whose `sync: true`
          asks for one. Only relevant when the image manifest declares a
          `deployed_as` with `sync: true`.
        required: false
        type: boolean
        default: true
      sync_aws_role_arn: # group: Image sync
        description: >-
          IAM role to assume via OIDC before syncing, for an ECR destination.
          When set, this workflow runs configure-aws-credentials and
          amazon-ecr-login before the bump. Not a secret: a role ARN is not
          sensitive, and OIDC needs no stored credential. The role's trust
          policy keys on this *calling* repo (e.g.
          `repo:my-org/my-deploy-repo:*`) -- the OIDC subject describes the
          caller even though the login runs here, so each deploy repo gets its
          own tightly scoped role and nothing has to trust every caller of this
          workflow.
        required: false
        type: string
        default: ""
      sync_aws_region: # group: Image sync
        description: AWS region for sync_aws_role_arn.
        required: false
        type: string
        default: ""
    outputs:
      image_name:
        description: Image name the bump ran for (no tag or digest).
        value: ${{ jobs.bump.outputs.image_name }}
      digest:
        description: Digest (sha256:...) of the image the bump ran for.
        value: ${{ jobs.bump.outputs.digest }}
      changed:
        description: Whether any manifest content changed ("true"/"false").
        value: ${{ jobs.bump.outputs.changed }}
      update_mode:
        description: Resolved update mode ("commit" or "pull_request").
        value: ${{ jobs.bump.outputs.update_mode }}
      environment:
        description: >-
          GitHub environment name resolved from the image manifest config for
          deployment reporting; empty when unconfigured.
        value: ${{ jobs.bump.outputs.environment }}
      environment_url:
        description: >-
          Deployment "View deployment" URL resolved from the image manifest
          config; empty when unconfigured.
        value: ${{ jobs.bump.outputs.environment_url }}
      branch_name:
        description: >-
          Branch name a pull_request-mode bump uses
          (odp-releaser/bump-<image_name>).
        value: ${{ jobs.bump.outputs.branch_name }}
      commit_message:
        description: Full commit message for the bump.
        value: ${{ jobs.bump.outputs.commit_message }}
      pr_title:
        description: Title for the bump pull request.
        value: ${{ jobs.bump.outputs.pr_title }}
      reviewers:
        description: >-
          Comma-separated GitHub usernames requested as reviewers on the bump
          pull request; empty when none are configured.
        value: ${{ jobs.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: ${{ jobs.bump.outputs.team_reviewers }}
      comment_enabled:
        description: >-
          Whether commenting back on the source pull request is enabled for this
          image ("true"/"false").
        value: ${{ jobs.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: ${{ jobs.bump.outputs.comment_pr_number }}
      comment_staged_template:
        description: >-
          Resolved comment template for a bump pull request awaiting review,
          unrendered.
        value: ${{ jobs.bump.outputs.comment_staged_template }}
      comment_deployed_template:
        description: Resolved comment template for a landed bump, unrendered.
        value: ${{ jobs.bump.outputs.comment_deployed_template }}
      sync_destinations:
        description: >-
          Newline-separated destination references the image was copied to;
          empty when no config asked for a sync.
        value: ${{ jobs.bump.outputs.sync_destinations }}
      synced:
        description: Whether the image sync actually ran ("true"/"false").
        value: ${{ jobs.bump.outputs.synced }}
    secrets:
      ci_app_id:
        description: >-
          Optional App ID of this repo's GitHub App. When set, the commit/PR is
          authored with an app token so it triggers this repo's own CI. Also
          needed for `team_reviewers` in the image manifest config: when that
          key is present, the app token is minted with organization "Members:
          read" added, so the app must be granted that permission.
        required: false
      ci_app_private_key:
        description: Optional private key matching ci_app_id.
        required: false
      reporter_apps:
        description: >-
          Optional JSON object mapping source owner -> {app_id, private_key}
          reporter app credentials, for deploy repos that receive dispatches
          from multiple source orgs. Also used to check `allowed_actors` team
          membership against source orgs (the app needs organization "Members:
          read" there).
        required: false
      reporter_app_id:
        description: >-
          Optional App ID of the source org's reporter GitHub App. When set
          (with reporter_app_private_key), a successful bump is reported back to
          the source repo as a GitHub deployment + status, and `allowed_actors`
          team membership is checked with it (the app needs organization
          "Members: read" for that). Commenting on the source pull request
          additionally needs "Pull requests: Read and write"; without it the
          comment step fails harmlessly and the deployment report still lands.
        required: false
      reporter_app_private_key:
        description: Optional private key matching reporter_app_id.
        required: false
      sync_registry: # group: Image sync
        description: >-
          Registry host to `docker login` to before syncing, for a destination
          that uses username/password auth (GHCR, Docker Hub). Leave unset when
          using sync_aws_role_arn, or when no config asks for a sync.
        required: false
      sync_username: # group: Image sync
        description: Username for sync_registry.
        required: false
      sync_password: # group: Image sync
        description: Password or token for sync_registry.
        required: false
      sync_source_registry: # group: Image sync
        description: >-
          Registry host to `docker login` to for the *source* side of a sync.
          Only needed when the image is pulled from somewhere that requires
          credentials the runner doesn't already have -- a private registry on a
          different host than the destination, or Docker Hub, where an anonymous
          pull shares the runner's IP rate limit. Since a failed copy fails the
          bump on purpose, an unauthenticated source is a source of intermittent
          release failures.
        required: false
      sync_source_username: # group: Image sync
        description: Username for sync_source_registry.
        required: false
      sync_source_password: # group: Image sync
        description: Password or token for sync_source_registry.
        required: false

permissions: {}

jobs:
  bump:
    name: Bump ${{ github.event.client_payload.image_name }} image
    runs-on: ubuntu-latest
    permissions:
      contents: write # commit the bump directly or push a PR branch
      pull-requests: write # open the bump pull request
      # Only actually used when sync_aws_role_arn is set, but `permissions`
      # cannot be conditional -- and a called workflow's permissions can only
      # be maintained or reduced, never elevated, relative to the caller. So
      # every caller has to grant this even if it never syncs; see the
      # "Upgrading" note in this file's header.
      id-token: write # assume the sync role via OIDC
    env:
      HAS_CI_APP: ${{ secrets.ci_app_id != '' }}
      HAS_REPORTER_APP:
        ${{ secrets.reporter_app_id != '' || secrets.reporter_apps != '' }}
      # The `secrets` context is not available in a step-level `if:`, so the
      # presence check has to be hoisted to the job env like the two above.
      HAS_SYNC_LOGIN: ${{ secrets.sync_registry != '' }}
      HAS_SYNC_SOURCE_LOGIN: ${{ secrets.sync_source_registry != '' }}
    concurrency:
      # client_payload.image_name is empty when this workflow is called
      # outside a repository_dispatch run (e.g. this repo's e2e CI); fall
      # back to a run-scoped group so unrelated runs never share a queue.
      group:
        odp-releaser-${{ github.event.client_payload.image_name || github.run_id
        }}
      cancel-in-progress: false
    outputs:
      image_name: ${{ steps.bump.outputs.image_name }}
      digest: ${{ steps.bump.outputs.digest }}
      changed: ${{ steps.bump.outputs.changed }}
      update_mode: ${{ steps.bump.outputs.update_mode }}
      environment: ${{ steps.bump.outputs.environment }}
      environment_url: ${{ steps.bump.outputs.environment_url }}
      branch_name: ${{ steps.bump.outputs.branch_name }}
      commit_message: ${{ steps.bump.outputs.commit_message }}
      pr_title: ${{ steps.bump.outputs.pr_title }}
      reviewers: ${{ steps.bump.outputs.reviewers }}
      team_reviewers: ${{ steps.bump.outputs.team_reviewers }}
      comment_enabled: ${{ steps.bump.outputs.comment_enabled }}
      comment_pr_number: ${{ steps.bump.outputs.comment_pr_number }}
      comment_staged_template: ${{ steps.bump.outputs.comment_staged_template }}
      comment_deployed_template:
        ${{ steps.bump.outputs.comment_deployed_template }}
      sync_destinations: ${{ steps.bump.outputs.sync_destinations }}
      synced: ${{ steps.bump.outputs.synced }}
    steps:
      - name: Generate app token
        id: app-token
        if: env.HAS_CI_APP == 'true'
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ secrets.ci_app_id }}
          private-key: ${{ secrets.ci_app_private_key }}
          # Scope the app token to only what the bump commit/PR needs.
          permission-contents: write
          permission-pull-requests: write

      - name: Checkout repository
        # persist-credentials stays true so the "Commit bump" step can git push.
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.0 # zizmor: ignore[artipacked]
        with:
          token: ${{ steps.app-token.outputs.token || github.token }}
          persist-credentials: true

      - name: Check the image manifest for team reviewers
        # Requesting a team review on the bump PR needs organization
        # "Members: read" on the token. Detect `team_reviewers` in the
        # manifest so the extra permission is only requested when the config
        # actually asks for team reviews — apps without the permission keep
        # working otherwise.
        id: team-config
        if: env.HAS_CI_APP == 'true'
        env:
          CONFIG_PATH: ${{ inputs.config_path }}
        run: |
          needed=false
          if [ -f "$CONFIG_PATH" ] && grep -Eq '^[^#]*\bteam_reviewers[[:space:]]*:' "$CONFIG_PATH"; then
            needed=true
          fi
          echo "needed=$needed" >> "$GITHUB_OUTPUT"

      - name: Generate app token with members read
        id: app-token-members
        if:
          env.HAS_CI_APP == 'true' && steps.team-config.outputs.needed == 'true'
        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
        with:
          client-id: ${{ secrets.ci_app_id }}
          private-key: ${{ secrets.ci_app_private_key }}
          permission-contents: write
          permission-pull-requests: write
          permission-members: read

      - name: Install ODP Releaser
        uses: $/.github/actions/install
        with:
          cache_suffix: odp-releaser-${{ job.workflow_sha }}

      # Registry logins for the image sync, both no-ops when unconfigured.
      # They run before the bump because the sync happens inside the
      # bump_images action, between writing the manifests and committing
      # them. skopeo picks these credentials up from
      # $HOME/.docker/config.json via the containers credential search
      # order, so no `skopeo login` is needed.
      - name: Configure AWS credentials for the sync
        if: inputs.sync_aws_role_arn != ''
        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
        with:
          role-to-assume: ${{ inputs.sync_aws_role_arn }}
          aws-region: ${{ inputs.sync_aws_region }}

      - name: Log in to Amazon ECR for the sync
        if: inputs.sync_aws_role_arn != ''
        uses: aws-actions/amazon-ecr-login@d539f0932e70871a027e9d5a9d8fc38589180a64 # v2.1.6

      - name: Log in to the sync registry
        if: env.HAS_SYNC_LOGIN == 'true'
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ secrets.sync_registry }}
          username: ${{ secrets.sync_username }}
          password: ${{ secrets.sync_password }}

      # The source side. The steps above authenticate the destination only,
      # but the copy also has to *pull*, and `sync_source_ref` names the
      # upstream registry -- which may be private, or may be Docker Hub, where
      # an anonymous pull is subject to the shared runner IP's rate limit.
      - name: Log in to the sync source registry
        if: env.HAS_SYNC_SOURCE_LOGIN == 'true'
        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4.6.0
        with:
          registry: ${{ secrets.sync_source_registry }}
          username: ${{ secrets.sync_source_username }}
          password: ${{ secrets.sync_source_password }}

      - name: Bump images
        id: bump
        uses: $/.github/actions/bump_images
        with:
          sync: ${{ inputs.sync }}
          client_payload:
            ${{ inputs.client_payload || toJSON(github.event.client_payload) }}
          config_path: ${{ inputs.config_path }}
          verbosity: ${{ inputs.verbosity }}
          git_user_name: ${{ inputs.git_user_name }}
          git_user_email: ${{ inputs.git_user_email }}
          dry_run: ${{ inputs.dry_run }}
          token:
            ${{ steps.app-token-members.outputs.token ||
            steps.app-token.outputs.token || github.token }}
          reporter_apps: ${{ secrets.reporter_apps }}
          reporter_app_id: ${{ secrets.reporter_app_id }}
          reporter_app_private_key: ${{ secrets.reporter_app_private_key }}

      - name: Bump commit URL
        # The bump_images action pushed the commit, so HEAD is the bump
        # commit; capture its URL as the deployment's "View deployment" link
        # fallback for commit-mode bumps.
        id: commit-url
        if:
          env.HAS_REPORTER_APP == 'true' && inputs.dry_run != true &&
          steps.bump.outputs.changed == 'true' && steps.bump.outputs.update_mode
          == 'commit'
        run: |
          printf 'url=%s/%s/commit/%s\n' \
            "$GITHUB_SERVER_URL" "$GITHUB_REPOSITORY" "$(git rev-parse HEAD)" \
            >> "$GITHUB_OUTPUT"

      - name: Report deployment to source repo
        # Best effort: a failed report never fails the bump itself.
        if:
          env.HAS_REPORTER_APP == 'true' && inputs.dry_run != true &&
          steps.bump.outputs.changed == 'true'
        continue-on-error: true
        uses: $/.github/actions/report_deployment
        with:
          client_payload:
            ${{ inputs.client_payload || toJSON(github.event.client_payload) }}
          update_mode: ${{ steps.bump.outputs.update_mode }}
          environment: ${{ steps.bump.outputs.environment }}
          environment_url:
            ${{ steps.bump.outputs.environment_url ||
            steps.bump.outputs.pull_request_url || steps.commit-url.outputs.url
            }}
          verbosity: ${{ inputs.verbosity }}
          reporter_apps: ${{ secrets.reporter_apps }}
          reporter_app_id: ${{ secrets.reporter_app_id }}
          reporter_app_private_key: ${{ secrets.reporter_app_private_key }}

      - name: Comment on source pull request
        # Best effort, like the deployment report above: a failed comment never
        # fails the bump. Skipped outright when the image manifest turned
        # commenting off, or when the triggering event carried no source pull
        # request to comment on (only push events do).
        if:
          env.HAS_REPORTER_APP == 'true' && inputs.dry_run != true &&
          steps.bump.outputs.changed == 'true' &&
          steps.bump.outputs.comment_enabled == 'true' &&
          steps.bump.outputs.comment_pr_number != ''
        continue-on-error: true
        uses: $/.github/actions/comment_on_pr
        with:
          client_payload:
            ${{ inputs.client_payload || toJSON(github.event.client_payload) }}
          update_mode: ${{ steps.bump.outputs.update_mode }}
          environment: ${{ steps.bump.outputs.environment }}
          environment_url: ${{ steps.bump.outputs.environment_url }}
          # Where the bump landed: the pull request for a PR-mode bump, the
          # bump commit for a direct one.
          bump_url:
            ${{ steps.bump.outputs.pull_request_url ||
            steps.commit-url.outputs.url }}
          pr_number: ${{ steps.bump.outputs.comment_pr_number }}
          comment_enabled: ${{ steps.bump.outputs.comment_enabled }}
          staged_template: ${{ steps.bump.outputs.comment_staged_template }}
          deployed_template: ${{ steps.bump.outputs.comment_deployed_template }}
          verbosity: ${{ inputs.verbosity }}
          reporter_apps: ${{ secrets.reporter_apps }}
          reporter_app_id: ${{ secrets.reporter_app_id }}
          reporter_app_private_key: ${{ secrets.reporter_app_private_key }}