code-maven_java-release-core.yml

# SPDX-FileCopyrightText: 2026 INDUSTRIA DE DISEÑO TEXTIL S.A. (INDITEX S.A.)
# SPDX-License-Identifier: Apache-2.0

name: code-maven-java-release-core

on:
  workflow_call:
    inputs:
      phase:
        description: Release lifecycle phase to execute.
        required: false
        type: string
        default: prepare
      promote:
        description: Whether successful external publication authorizes promotion.
        required: false
        type: boolean
        default: false
      release_type:
        description: Optional release type supplied by the fixed release workflow.
        required: false
        type: string
        default: ''
      release_commit:
        description: Prepared release commit supplied to the finalize phase.
        required: false
        type: string
        default: ''
      promote_commit:
        description: Prepared next-development commit supplied to the finalize phase.
        required: false
        type: string
        default: ''
      releases:
        description: Prepared release records supplied to the finalize phase.
        required: false
        type: string
        default: '[]'
      expected_ref:
        description: Baseline ref expected by the finalize phase.
        required: false
        type: string
        default: ''
      staging_ref:
        description: Run-scoped staging ref supplied to the finalize phase.
        required: false
        type: string
        default: ''
      staged_tag_ref:
        description: Run-scoped staged tag ref supplied to the finalize phase.
        required: false
        type: string
        default: ''
    outputs:
      release_commit:
        description: Immutable commit used to build the release artifacts.
        value: ${{ jobs.prepare-release.outputs.release_commit }}
      promote_commit:
        description: Prepared next-development commit to promote after publication.
        value: ${{ jobs.prepare-release.outputs.promote_commit }}
      releases:
        description: JSON array of release tags, versions, module lists, and next-dev versions.
        value: ${{ jobs.prepare-release.outputs.releases }}
      expected_ref:
        description: Baseline ref expected by the promotion.
        value: ${{ jobs.prepare-release.outputs.expected_ref }}
      staging_ref:
        description: Run-scoped ref that holds the prepared release.
        value: ${{ jobs.prepare-release.outputs.staging_ref }}
      staged_tag_ref:
        description: Run-scoped ref that holds a delegated release tag.
        value: ${{ jobs.prepare-release.outputs.staged_tag_ref }}
    secrets:
      APP_PRIVATE_KEY:
        required: true

permissions:
  actions: read
  contents: read

env:
  CI_GOVERNANCE_RELEASE_STAGING_REF: refs/ci-governance/release/${{ github.run_id }}-${{ github.run_attempt }}
  CI_GOVERNANCE_RELEASE_TAG_STAGING_REF: refs/ci-governance/release-tag/${{ github.run_id }}-${{ github.run_attempt }}
  WORKING_DIRECTORY: ${{ vars.WORKING_DIRECTORY }}
  ASDF_BRANCH_VERSION: '0.18.0'

jobs:
  prepare-release:
    name: Prepare Release
    if: >-
      inputs.phase != 'finalize' && ((
        github.event_name == 'workflow_dispatch'
      ) ||
      (
        github.event_name == 'pull_request' &&
        github.event.pull_request.merged &&
        github.event.pull_request.head.repo.full_name == github.repository &&
        github.event.pull_request.head.ref != 'automated/ci-governance-sync' &&
        !contains(join(github.event.pull_request.labels.*.name, ','), 'skip-release') &&
        (
          contains(join(github.event.pull_request.labels.*.name, ','), 'release-type') ||
          vars.DEVELOPMENT_FLOW == 'trunk-based-development'
        )
      ))
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    outputs:
      release_commit: ${{ steps.release-metadata.outputs.release_commit }}
      promote_commit: ${{ steps.release-metadata.outputs.promote_commit }}
      releases: ${{ steps.release-metadata.outputs.releases }}
      expected_ref: ${{ steps.release-metadata.outputs.expected_ref }}
      lifecycle_mode: ${{ steps.lifecycle.outputs.mode }}
      staging_ref: ${{ steps.release-metadata.outputs.staging_ref }}
      staged_tag_ref: ${{ steps.release-metadata.outputs.staged_tag_ref }}
      release_source_artifact: ${{ steps.release-source-handoff.outputs.artifact_name }}
      release_source_sha256: ${{ steps.release-source-handoff.outputs.bundle_sha256 }}
    steps:
      - name: Resolve release context
        id: release-context
        env:
          EVENT_SHA: ${{ github.sha }}
          PR_BASE_BRANCH: ${{ github.event.pull_request.base.ref }}
          PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
          PR_MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
          REQUESTED_RELEASE_TYPE: ${{ inputs.release_type }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          GIT_FLOW_RELEASE_BRANCH: ${{ vars.GIT_FLOW_RELEASE_BRANCH }}
        shell: bash
        run: |
          set -euo pipefail

          if [[ "$GITHUB_EVENT_NAME" == "workflow_dispatch" ]]; then
            baseline_branch="$GITHUB_REF_NAME"
            release_labels="$REQUESTED_RELEASE_TYPE"
            release_ref="$EVENT_SHA"
          else
            baseline_branch="$PR_BASE_BRANCH"
            release_labels="$PR_LABELS"
            release_ref="$PR_MERGE_SHA"
          fi

          if [[ "$DEVELOPMENT_FLOW" == "trunk-based-development" ]]; then
            release_branch="main"
          elif [[ "$DEVELOPMENT_FLOW" == "git-flow" ]]; then
            release_branch="$GIT_FLOW_RELEASE_BRANCH"
          else
            echo "::error title=Invalid development flow::DEVELOPMENT_FLOW must be trunk-based-development or git-flow."
            exit 1
          fi

          if [[ -z "$release_branch" ]]; then
            echo "::error title=Missing git-flow release branch::GIT_FLOW_RELEASE_BRANCH is required for git-flow releases."
            exit 1
          fi

          if [[ "$baseline_branch" == "$release_branch"- ]]; then
            echo "::error title=Invalid release branch::${baseline_branch} has no release suffix."
            exit 1
          fi

          if [[ "$baseline_branch" != "$release_branch" && "$baseline_branch" != "$release_branch"-* ]]; then
            echo "::error title=Invalid release branch::${baseline_branch} is not a configured release branch."
            exit 1
          fi

          if [[ -z "$baseline_branch" || ! "$release_ref" =~ ^[0-9a-f]{40}$ ]]; then
            echo "::error title=Invalid release context::A baseline branch and immutable release commit are required."
            exit 1
          fi

          {
            echo "baseline_branch=$baseline_branch"
            echo "release_labels=$release_labels"
            echo "release_ref=$release_ref"
          } >> "$GITHUB_OUTPUT"

      - name: Enforce protected release branch
        env:
          GH_TOKEN: ${{ github.token }}
          BASELINE_BRANCH: ${{ steps.release-context.outputs.baseline_branch }}
        shell: bash
        run: |
          set -euo pipefail
          protected="$(gh api "repos/${GITHUB_REPOSITORY}/branches/${BASELINE_BRANCH}" --jq '.protected')"
          if [[ "$protected" != "true" ]]; then
            echo "::error title=Unprotected release branch::Releases require a protected baseline branch; '${BASELINE_BRANCH}' is not protected." >&2
            exit 1
          fi

      - name: Create GitHub App token
        id: app-token
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          permission-contents: write
          permission-pull-requests: write

      - name: Check out immutable release source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ steps.release-context.outputs.release_ref }}
          token: ${{ steps.app-token.outputs.token }}

      - name: Resolve governed project type
        shell: bash
        run: |
          set -euo pipefail
          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          if [[ ! -f "$descriptor" ]]; then
            echo "::error title=Missing descriptor::.github/inditextech-ci-java.json not found."
            exit 1
          fi
          project_type="$(jq -r '.project_type // empty' "$descriptor")"
          case "$project_type" in
            single|monorepo) ;;
            *)
              echo "::error title=Invalid project type::Descriptor .project_type must be single or monorepo."
              exit 1
              ;;
          esac
          workdir="${WORKING_DIRECTORY:-$(jq -r '.working_directory // empty' "$descriptor")}"
          case "$workdir" in
            ""|/*|..|../*|*/..|*/../*)
              echo "::error title=Invalid working directory::WORKING_DIRECTORY must be a non-empty relative repository path." >&2
              exit 1
              ;;
          esac
          if [[ ! -d "$workdir" ]]; then
            echo "::error title=Missing working directory::'${workdir}' is not a directory in this checkout." >&2
            exit 1
          fi
          echo "WORKING_DIRECTORY=${workdir}" >> "$GITHUB_ENV"
          echo "PROJECT_TYPE=$project_type" >> "$GITHUB_ENV"

      - name: Require pending CHANGELOG entries
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          changelog="CHANGELOG.md"
          if [[ ! -f "$changelog" ]]; then
            echo "::error title=Missing CHANGELOG::${WORKING_DIRECTORY}/CHANGELOG.md is required before a release."
            exit 1
          fi
          if ! awk '
            $0 ~ /^##[[:space:]]+\[Unreleased\][[:space:]]*$/ { unreleased = 1; next }
            unreleased && $0 ~ /^##[[:space:]]/ { exit }
            unreleased && $0 ~ /^[[:space:]]*([-*+]|\[[^]]+\]|[0-9]+\.)[[:space:]]+/ { entry = 1 }
            END { exit !(unreleased && entry) }
          ' "$changelog"; then
            echo "::error title=Missing pending CHANGELOG entry::CHANGELOG.md must contain a substantive entry under ## [Unreleased]."
            exit 1
          fi

      - name: Resolve release lifecycle
        id: lifecycle
        shell: bash
        run: |
          set -euo pipefail
          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          mode="$(jq -r '.release.lifecycle // "govern-inject"' "$descriptor")"
          case "$mode" in
            govern-inject|delegated) ;;
            *)
              echo "::error title=Invalid release lifecycle::release.lifecycle must be govern-inject or delegated."
              exit 1
              ;;
          esac
          echo "mode=$mode" >> "$GITHUB_OUTPUT"

      - name: Set up workflow Java
        uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
        with:
          distribution: temurin
          java-version: '25.0.2+10.0.LTS'
          cache: maven
          cache-dependency-path: ${{ env.WORKING_DIRECTORY }}/**/pom.xml

      - name: Read governed tool versions
        id: tool-versions
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if grep -Evq '^[a-zA-Z0-9_-]+ [a-zA-Z0-9._+-]+$' .tool-versions; then
            echo "::error title=Invalid tool-versions::${WORKING_DIRECTORY}/.tool-versions is malformed."
            exit 1
          fi
          {
            echo "tool_versions<<EOF"
            cat .tool-versions
            echo
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Set up asdf-managed Java
        uses: asdf-vm/actions/install@b7bcd026f18772e44fe1026d729e1611cc435d47 # v4.0.1
        with:
          tool_versions: ${{ steps.tool-versions.outputs.tool_versions }}
          asdf_version: ${{ env.ASDF_BRANCH_VERSION }}

      - name: Resolve build JDK from .tool-versions
        id: jdk
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          echo "java_home=$(asdf where java)" >> "$GITHUB_OUTPUT"

      - name: Verify release candidate
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        env:
          JAVA_HOME: ${{ steps.jdk.outputs.java_home }}
        run: |
          set -euo pipefail
          case "$PROJECT_TYPE" in
            single|monorepo)
              mvn -B --no-transfer-progress -f pom.xml clean verify -DskipITs
              ;;
            *)
              echo "::error title=Invalid project type::PROJECT_TYPE must be single or monorepo."
              exit 1
              ;;
          esac

      - name: Plan release metadata
        id: release-plan
        if: steps.lifecycle.outputs.mode != 'delegated'
        env:
          JAVA_HOME: ${{ steps.jdk.outputs.java_home }}
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          BASELINE_BRANCH: ${{ steps.release-context.outputs.baseline_branch }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASE_LABELS: ${{ steps.release-context.outputs.release_labels }}
          RELEASE_REF: ${{ steps.release-context.outputs.release_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail

          gh auth setup-git

          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          records_file="$RUNNER_TEMP/java-release-records.jsonl"
          modules_file="$RUNNER_TEMP/java-release-modules.txt"
          source_commit="$(git rev-parse "$RELEASE_REF^{commit}")"
          expected_ref="refs/heads/$BASELINE_BRANCH"
          remote_line="$(git ls-remote --exit-code origin "$expected_ref")"
          read -r remote_commit remote_ref extra <<< "$remote_line"

          if [[ "$remote_ref" != "$expected_ref" || -n "${extra:-}" ]]; then
            echo "::error title=Release branch verification failed::Could not resolve exactly one destination branch."
            exit 1
          fi

          resume="false"
          release_commit=""
          if [[ "$remote_commit" != "$source_commit" ]]; then
            git fetch --no-tags origin "$remote_commit"
            release_commit="$(git rev-list --ancestry-path --reverse "${source_commit}..${remote_commit}" | head -1)"
            if [[ -z "$release_commit" ]] \
              || [[ "$(git rev-parse "${release_commit}^")" != "$source_commit" ]] \
              || [[ "$(git show -s --format=%s "$release_commit")" != "[java-release] Prepare release" ]]; then
              echo "::error title=Release branch advanced::The destination branch moved after the release source commit."
              exit 1
            fi
            git checkout --detach "$release_commit"
            resume="true"
          fi

          case ",$RELEASE_LABELS," in
            *",release-type/major,"*) release_bump="major" ;;
            *",release-type/minor,"*) release_bump="minor" ;;
            *",release-type/hotfix,"*|*",release-type/multi-hotfix,"*|*",release-type/patch,"*)
              release_bump="patch"
              ;;
            *)
              if [[ "$DEVELOPMENT_FLOW" == "trunk-based-development" ]]; then
                release_bump="minor"
              else
                echo "::error title=Missing release type::git-flow releases require a release-type label."
                exit 1
              fi
              ;;
          esac

          artifact_id() {
            printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//'
          }
          strip_snapshot() { printf '%s' "${1%-SNAPSHOT}"; }
          # Resolve declared Maven artifactIds through the reactor.
          read_version() {
            if [[ -n "$1" ]]; then
              mvn -q -B --no-transfer-progress -f pom.xml -pl ":$1" \
                help:evaluate -Dexpression=project.version -DforceStdout
            else
              mvn -q -B --no-transfer-progress -f pom.xml \
                help:evaluate -Dexpression=project.version -DforceStdout
            fi
          }
          read_artifact() {
            if [[ -n "$1" ]]; then
              mvn -q -B --no-transfer-progress -f pom.xml -pl ":$1" \
                help:evaluate -Dexpression=project.artifactId -DforceStdout
            else
              mvn -q -B --no-transfer-progress -f pom.xml \
                help:evaluate -Dexpression=project.artifactId -DforceStdout
            fi
          }
          bump_semver() {
            local major minor patch
            IFS=. read -r major minor patch <<< "$1"
            case "$2" in
              major) major=$((major + 1)); minor=0; patch=0 ;;
              minor) minor=$((minor + 1)); patch=0 ;;
              patch) patch=$((patch + 1)) ;;
            esac
            printf '%s.%s.%s' "$major" "$minor" "$patch"
          }
          set_version() {
            if [[ -n "$2" ]]; then
              mvn -q -B --no-transfer-progress -f pom.xml versions:set \
                -DgroupId=com.inditextech -DartifactId="$2" -DoldVersion='*' \
                -DnewVersion="$1" -DprocessAllModules=false -DgenerateBackupPoms=false
            elif [[ "$PROJECT_TYPE" == "monorepo" ]]; then
              mvn -q -B --no-transfer-progress -f pom.xml versions:set \
                -DnewVersion="$1" -DprocessAllModules=true -DgenerateBackupPoms=false
            else
              mvn -q -B --no-transfer-progress -f pom.xml versions:set \
                -DnewVersion="$1" -DgenerateBackupPoms=false
            fi
          }

          if [[ "$PROJECT_TYPE" == "single" ]]; then
            release_strategy=single
            printf '%s\n' "$(read_artifact "")" > "$modules_file"
          elif [[ "$PROJECT_TYPE" == "monorepo" ]]; then
            release_strategy="$(jq -er '.release.strategy' "$descriptor")"
            : > "$modules_file"
            while IFS= read -r package; do
              printf '%s\n' "$(artifact_id "$package")" >> "$modules_file"
            done < <(jq -er '.release.packages[]' "$descriptor")
          else
            echo "::error title=Invalid project type::PROJECT_TYPE must be single or monorepo."
            exit 1
          fi

          write_records() {
            : > "$records_file"
            if [[ "$release_strategy" == "single" ]]; then
              artifact="$(<"$modules_file")"
              version="$(strip_snapshot "$(read_version "")")"
              next_dev="$(bump_semver "$version" "$release_bump")-SNAPSHOT"
              jq -cn \
                --arg artifact "$artifact" \
                --arg version "$version" \
                --arg tag "$version" \
                --arg next_dev "$next_dev" \
                '{packages: [$artifact], version: $version, tag: $tag, next_dev: $next_dev}' >> "$records_file"
              return
            fi

            if [[ "$release_strategy" == "locked-step" ]]; then
              modules=()
              while IFS= read -r module; do
                modules+=("$module")
              done < "$modules_file"
              versions=()
              for module in "${modules[@]}"; do
                versions+=("$(strip_snapshot "$(read_version "$module")")")
              done
              if [[ "$(printf '%s\n' "${versions[@]}" | sort -u | wc -l | tr -d ' ')" -ne 1 ]]; then
                echo "::error title=Invalid locked-step reactor::All release modules must share the same version."
                exit 1
              fi
              version="${versions[0]}"
              next_dev="$(bump_semver "$version" "$release_bump")-SNAPSHOT"
              jq -cn \
                --arg version "$version" \
                --arg tag "$version" \
                --arg next_dev "$next_dev" \
                '{packages: [], version: $version, tag: $tag, next_dev: $next_dev}' >> "$records_file"
              return
            fi

            while IFS= read -r module; do
              version="$(strip_snapshot "$(read_version "$module")")"
              next_dev="$(bump_semver "$version" "$release_bump")-SNAPSHOT"
              jq -cn \
                --arg module "$module" \
                --arg version "$version" \
                --arg tag "${module}-${version}" \
                --arg next_dev "$next_dev" \
                '{packages: [$module], version: $version, tag: $tag, next_dev: $next_dev}' >> "$records_file"
            done < "$modules_file"
          }

          if [[ "$resume" == "false" ]]; then
            write_records
            releases="$(jq -cs . "$records_file")"

            if [[ "$release_strategy" == "independent" ]]; then
              while IFS= read -r record; do
                artifact="$(jq -r '.packages[0]' <<< "$record")"
                version="$(jq -r '.version' <<< "$record")"
                set_version "$version" "$artifact"
              done < <(jq -c '.[]' <<< "$releases")
            else
              set_version "$(jq -r '.[0].version' <<< "$releases")" ""
            fi

            while IFS= read -r tag; do
              if git show-ref --tags --verify --quiet "refs/tags/$tag"; then
                echo "::error title=Tag conflict::$tag already exists."
                exit 1
              fi
            done < <(jq -r '.[].tag' <<< "$releases")

            git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
            if git diff --cached --quiet; then
              echo "::error title=Missing release metadata::Versioning did not produce changes to commit."
              exit 1
            fi

            primary_version="$(jq -r '.[0].version' <<< "$releases")"
            echo "RELEASE_VERSION=$primary_version" >> "$GITHUB_ENV"
            echo "RELEASE_BUMP=$release_bump" >> "$GITHUB_ENV"
          else
            write_records
            releases="$(jq -cs . "$records_file")"
            head_commit="$(git rev-parse HEAD)"
            while IFS= read -r tag; do
              if [[ "$(git rev-list -n 1 "$tag")" != "$head_commit" ]]; then
                echo "::error title=Incomplete release resume::$tag does not point to the release commit."
                exit 1
              fi
            done < <(jq -r '.[].tag' <<< "$releases")
          fi

          {
            echo "resume=$resume"
            echo "expected_ref=$expected_ref"
            echo "releases_intermediate<<EOF"
            printf '%s\n' "$releases"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Bump CHANGELOG for release
        if: steps.release-plan.outputs.resume != 'true' && steps.lifecycle.outputs.mode != 'delegated'
        uses: release-flow/keep-a-changelog-action@74931dec7ecdbfc8e38ac9ae7e8dd84c08db2f32 # v3.0.0
        with:
          command: bump
          version: ${{ env.RELEASE_BUMP }}
          changelog: ${{ env.WORKING_DIRECTORY }}/CHANGELOG.md
          fail-on-empty-release-notes: false
          keep-unreleased-section: true
          tag-prefix: ""

      - name: Reconcile CHANGELOG version with release
        if: steps.release-plan.outputs.resume != 'true' && steps.lifecycle.outputs.mode != 'delegated'
        env:
          RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          cl="CHANGELOG.md"
          cl_ver="$(grep -m1 -E '^## \[[0-9]' "$cl" | sed -E 's/^## \[([^]]+)\].*/\1/')"
          if [[ -z "$cl_ver" ]]; then
            echo "::error title=CHANGELOG has no release entry::Expected a '## [X.Y.Z]' heading after the bump step."
            exit 1
          fi
          if [[ "$cl_ver" != "$RELEASE_VERSION" ]]; then
            echo "::notice title=CHANGELOG version reconciled::keep-a-changelog wrote ${cl_ver}; re-anchoring to release ${RELEASE_VERSION}."
            cl_ver_re="${cl_ver//./\\.}"
            tmp="$(mktemp)"
            sed -E \
              -e "s@^## \[${cl_ver_re}\]( - )@## [${RELEASE_VERSION}]\1@" \
              -e "s@^(\[Unreleased\]: .*/compare/)${cl_ver_re}(\.\.\.HEAD)@\1${RELEASE_VERSION}\2@" \
              -e "s@^\[${cl_ver_re}\]: (.*/)(compare/[^ ]*\.\.\.|releases/tag/)${cl_ver_re}@[${RELEASE_VERSION}]: \1\2${RELEASE_VERSION}@" \
              "$cl" > "$tmp"
            cat "$tmp" > "$cl"
            rm -f "$tmp"
          fi

      - name: Commit and stage release
        if: steps.release-plan.outputs.resume != 'true' && steps.lifecycle.outputs.mode != 'delegated'
        id: release-commit
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASES: ${{ steps.release-plan.outputs.releases_intermediate }}
          EXPECTED_REF: ${{ steps.release-plan.outputs.expected_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          git -C "$GITHUB_WORKSPACE" add -- "$WORKING_DIRECTORY/CHANGELOG.md"
          git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
          if git diff --cached --quiet; then
            echo "::error title=Missing release metadata::Versioning did not produce changes to commit."
            exit 1
          fi
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"
          git commit -m "[java-release] Prepare release"

          while IFS= read -r record; do
            git check-ref-format --allow-onelevel "refs/tags/$(jq -r '.tag' <<< "$record")"
          done < <(jq -c '.[]' <<< "$RELEASES")

          git push --atomic --force origin "HEAD:$CI_GOVERNANCE_RELEASE_STAGING_REF"

      - name: Plan delegated release
        id: delegated-plan
        if: steps.lifecycle.outputs.mode == 'delegated'
        env:
          JAVA_HOME: ${{ steps.jdk.outputs.java_home }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          RELEASE_LABELS: ${{ steps.release-context.outputs.release_labels }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          strip_snapshot() { printf '%s' "${1%-SNAPSHOT}"; }
          bump_semver() {
            local major minor patch
            IFS=. read -r major minor patch <<< "$1"
            case "$2" in
              major) major=$((major + 1)); minor=0; patch=0 ;;
              minor) minor=$((minor + 1)); patch=0 ;;
              patch) patch=$((patch + 1)) ;;
            esac
            printf '%s.%s.%s' "$major" "$minor" "$patch"
          }
          case ",$RELEASE_LABELS," in
            *",release-type/major,"*) release_bump="major" ;;
            *",release-type/minor,"*) release_bump="minor" ;;
            *",release-type/hotfix,"*|*",release-type/multi-hotfix,"*|*",release-type/patch,"*)
              release_bump="patch"
              ;;
            *)
              if [[ "$DEVELOPMENT_FLOW" == "trunk-based-development" ]]; then
                release_bump="minor"
              else
                echo "::error title=Missing release type::git-flow releases require a release-type label."
                exit 1
              fi
              ;;
          esac
          current_version="$(mvn -q -B --no-transfer-progress -f pom.xml \
            help:evaluate -Dexpression=project.version -DforceStdout)"
          release_version="$(strip_snapshot "$current_version")"
          next_dev="$(bump_semver "$release_version" "$release_bump")-SNAPSHOT"
          git -C "$GITHUB_WORKSPACE" tag --list | sort > "$RUNNER_TEMP/java-tags-before.txt"
          {
            echo "release_version=$release_version"
            echo "next_dev=$next_dev"
          } >> "$GITHUB_OUTPUT"
          echo "RELEASE_VERSION=$release_version" >> "$GITHUB_ENV"
          echo "RELEASE_BUMP=$release_bump" >> "$GITHUB_ENV"

      - name: Bump CHANGELOG for delegated release
        if: steps.lifecycle.outputs.mode == 'delegated'
        uses: release-flow/keep-a-changelog-action@74931dec7ecdbfc8e38ac9ae7e8dd84c08db2f32 # v3.0.0
        with:
          command: bump
          version: ${{ env.RELEASE_BUMP }}
          changelog: ${{ env.WORKING_DIRECTORY }}/CHANGELOG.md
          fail-on-empty-release-notes: false
          keep-unreleased-section: true
          tag-prefix: ""

      - name: Reconcile CHANGELOG version with delegated release
        if: steps.lifecycle.outputs.mode == 'delegated'
        env:
          RELEASE_VERSION: ${{ env.RELEASE_VERSION }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          cl="CHANGELOG.md"
          cl_ver="$(grep -m1 -E '^## \[[0-9]' "$cl" | sed -E 's/^## \[([^]]+)\].*/\1/')"
          if [[ -z "$cl_ver" ]]; then
            echo "::error title=CHANGELOG has no release entry::Expected a '## [X.Y.Z]' heading after the bump step."
            exit 1
          fi
          if [[ "$cl_ver" != "$RELEASE_VERSION" ]]; then
            echo "::notice title=CHANGELOG version reconciled::keep-a-changelog wrote ${cl_ver}; re-anchoring to release ${RELEASE_VERSION}."
            cl_ver_re="${cl_ver//./\\.}"
            tmp="$(mktemp)"
            sed -E \
              -e "s@^## \[${cl_ver_re}\]( - )@## [${RELEASE_VERSION}]\1@" \
              -e "s@^(\[Unreleased\]: .*/compare/)${cl_ver_re}(\.\.\.HEAD)@\1${RELEASE_VERSION}\2@" \
              -e "s@^\[${cl_ver_re}\]: (.*/)(compare/[^ ]*\.\.\.|releases/tag/)${cl_ver_re}@[${RELEASE_VERSION}]: \1\2${RELEASE_VERSION}@" \
              "$cl" > "$tmp"
            cat "$tmp" > "$cl"
            rm -f "$tmp"
          fi

      - name: Prepare delegated release
        id: delegated-release
        if: steps.lifecycle.outputs.mode == 'delegated'
        env:
          JAVA_HOME: ${{ steps.jdk.outputs.java_home }}
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          BASELINE_BRANCH: ${{ steps.release-context.outputs.baseline_branch }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          NEXT_DEV: ${{ steps.delegated-plan.outputs.next_dev }}
          RELEASE_VERSION: ${{ steps.delegated-plan.outputs.release_version }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          gh auth setup-git
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"

          git -C "$GITHUB_WORKSPACE" checkout -B "$BASELINE_BRANCH"

          packages_json='[]'
          if [[ "$PROJECT_TYPE" == "monorepo" ]]; then
            descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
            packages_json="$(jq -c '[(.release.packages // [])[] | ascii_downcase
              | gsub("[^a-z0-9]+"; "-") | gsub("^-+|-+$"; "")]' "$descriptor")"
            if [[ "$(jq -r 'length' <<< "$packages_json")" -eq 0 ]]; then
              echo "::error title=No release packages::A monorepo must declare release.packages in .github/inditextech-ci-java.json." >&2
              exit 1
            fi
          fi

          git -C "$GITHUB_WORKSPACE" add -- "$WORKING_DIRECTORY/CHANGELOG.md"
          if ! git -C "$GITHUB_WORKSPACE" diff --cached --quiet; then
            git -C "$GITHUB_WORKSPACE" commit -m "[java-release] Consume changelog for release $RELEASE_VERSION"
          fi

          baseline_before="$(git -C "$GITHUB_WORKSPACE" ls-remote origin "refs/heads/$BASELINE_BRANCH" | cut -f1)"
          git -C "$GITHUB_WORKSPACE" ls-remote --tags origin \
            | awk '{print $2}' | sort > "$RUNNER_TEMP/origin-tags-before.txt"

          real_git="$(command -v git)"
          interposer_dir="$(mktemp -d "$RUNNER_TEMP/ci-governance-git-interposer.XXXXXX")"
          interposer_log="$RUNNER_TEMP/ci-governance-git-interposer-blocked.log"
          : > "$interposer_log"
          cat > "$interposer_dir/git" <<'GIT_SHIM'
          #!/usr/bin/env bash
          set -euo pipefail
          subcommand=""
          skip_next="false"
          for arg in "$@"; do
            if [[ "$skip_next" == "true" ]]; then
              skip_next="false"
              continue
            fi
            case "$arg" in
              -C|-c|--git-dir|--work-tree|--namespace|--super-prefix|--exec-path|--config-env)
                skip_next="true"
                ;;
              --git-dir=*|--work-tree=*|--namespace=*|--super-prefix=*|--exec-path=*|--config-env=*)
                ;;
              -*)
                ;;
              *)
                subcommand="$arg"
                break
                ;;
            esac
          done
          if [[ "$subcommand" == "push" ]]; then
            {
              printf 'blocked: git'
              for arg in "$@"; do
                printf ' %q' "$arg"
              done
              printf '\n'
            } >> "$CI_GOVERNANCE_GIT_INTERPOSER_LOG"
            exit 0
          fi
          exec "$CI_GOVERNANCE_REAL_GIT" "$@"
          GIT_SHIM
          chmod +x "$interposer_dir/git"

          CI_GOVERNANCE_REAL_GIT="$real_git" \
            CI_GOVERNANCE_GIT_INTERPOSER_LOG="$interposer_log" \
            PATH="$interposer_dir:$PATH" \
            mvn -B --no-transfer-progress -f pom.xml \
            release:clean release:prepare \
            -DpushChanges=false \
            -DdevelopmentVersion="$NEXT_DEV" \
            -Darguments="-DskipTests -DskipEnforceSnapshots -DskipITs"

          if [[ -s "$interposer_log" ]]; then
            while IFS= read -r blocked_line; do
              echo "::notice title=Blocked plugin push::$blocked_line"
            done < "$interposer_log"
          fi

          baseline_after="$(git -C "$GITHUB_WORKSPACE" ls-remote origin "refs/heads/$BASELINE_BRANCH" | cut -f1)"
          git -C "$GITHUB_WORKSPACE" ls-remote --tags origin \
            | awk '{print $2}' | sort > "$RUNNER_TEMP/origin-tags-after.txt"
          leaked_refs=()
          while IFS= read -r ref; do
            [[ -n "$ref" ]] && leaked_refs+=("$ref")
          done < <(comm -13 "$RUNNER_TEMP/origin-tags-before.txt" "$RUNNER_TEMP/origin-tags-after.txt")

          if [[ "$baseline_after" != "$baseline_before" || "${#leaked_refs[@]}" -ne 0 ]]; then
            for ref in "${leaked_refs[@]}"; do
              git -C "$GITHUB_WORKSPACE" push origin --delete "$ref" \
                || echo "::warning title=Tag rollback failed::Could not delete $ref from origin."
            done
            if [[ "$baseline_after" != "$baseline_before" ]]; then
              git -C "$GITHUB_WORKSPACE" push \
                --force-with-lease="refs/heads/$BASELINE_BRANCH:$baseline_after" \
                origin "$baseline_before:refs/heads/$BASELINE_BRANCH" \
                || echo "::warning title=Baseline rollback failed::$BASELINE_BRANCH still carries commits release:prepare pushed; reset it to $baseline_before by hand."
            fi
            echo "::error title=Release published before it was built::maven-release-plugin wrote to origin during prepare-release despite the engine's git interposer. Treat this as an interposer bypass and escalate to the CI governance engine owners." >&2
            exit 1
          fi

          git -C "$GITHUB_WORKSPACE" tag --list | sort > "$RUNNER_TEMP/java-tags-after.txt"
          new_tags=()
          while IFS= read -r tag; do
            [[ -n "$tag" ]] && new_tags+=("$tag")
          done < <(comm -13 "$RUNNER_TEMP/java-tags-before.txt" "$RUNNER_TEMP/java-tags-after.txt")
          if [[ "${#new_tags[@]}" -ne 1 ]]; then
            echo "::error title=Ambiguous release tag::release:prepare must produce exactly one tag; found ${#new_tags[@]}."
            exit 1
          fi
          release_tag="${new_tags[0]}"
          release_commit="$(git -C "$GITHUB_WORKSPACE" rev-list -n 1 "$release_tag")"
          promote_commit="$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)"

          git -C "$GITHUB_WORKSPACE" push --atomic --force origin \
            "HEAD:$CI_GOVERNANCE_RELEASE_STAGING_REF" \
            "refs/tags/$release_tag:$CI_GOVERNANCE_RELEASE_TAG_STAGING_REF"
          git -C "$GITHUB_WORKSPACE" tag -d "$release_tag"

          releases="$(jq -cn \
            --argjson packages "$packages_json" \
            --arg version "$RELEASE_VERSION" \
            --arg tag "$release_tag" \
            --arg next_dev "$NEXT_DEV" \
            '[{packages: $packages, version: $version, tag: $tag, next_dev: $next_dev}]')"
          {
            echo "release_commit=$release_commit"
            echo "promote_commit=$promote_commit"
            echo "releases<<EOF"
            printf '%s\n' "$releases"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Publish release metadata
        id: release-metadata
        env:
          LIFECYCLE_MODE: ${{ steps.lifecycle.outputs.mode }}
          RELEASES: ${{ steps.release-plan.outputs.releases_intermediate }}
          DELEGATED_RELEASES: ${{ steps.delegated-release.outputs.releases }}
          DELEGATED_RELEASE_COMMIT: ${{ steps.delegated-release.outputs.release_commit }}
          DELEGATED_PROMOTE_COMMIT: ${{ steps.delegated-release.outputs.promote_commit }}
          BASELINE_BRANCH: ${{ steps.release-context.outputs.baseline_branch }}
          PLAN_EXPECTED_REF: ${{ steps.release-plan.outputs.expected_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ "$LIFECYCLE_MODE" == "delegated" ]]; then
            release_commit="$DELEGATED_RELEASE_COMMIT"
            release_records="$DELEGATED_RELEASES"
            promote_commit="$DELEGATED_PROMOTE_COMMIT"
            expected_ref="refs/heads/$BASELINE_BRANCH"
            staged_tag_ref="$CI_GOVERNANCE_RELEASE_TAG_STAGING_REF"
          else
            release_commit="$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)"
            release_records="$RELEASES"
            promote_commit="$release_commit"
            expected_ref="$PLAN_EXPECTED_REF"
            staged_tag_ref=""
          fi
          {
            echo "release_commit=$release_commit"
            echo "promote_commit=$promote_commit"
            echo "expected_ref=$expected_ref"
            echo "staging_ref=$CI_GOVERNANCE_RELEASE_STAGING_REF"
            echo "staged_tag_ref=$staged_tag_ref"
            echo "releases<<EOF"
            printf '%s\n' "$release_records"
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Create release source handoff
        id: release-source-handoff
        env:
          SOURCE_COMMIT: ${{ steps.release-metadata.outputs.release_commit }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ ! "$SOURCE_COMMIT" =~ ^[0-9a-f]{40}$ ]] \
            || ! git -C "$GITHUB_WORKSPACE" cat-file -e "$SOURCE_COMMIT^{commit}"; then
            echo "::error title=Invalid release source::Release metadata did not provide a local immutable commit." >&2
            exit 1
          fi
          handoff_dir="$RUNNER_TEMP/release-source"
          bundle="$handoff_dir/release.bundle"
          metadata="$handoff_dir/release-metadata.json"
          artifact_name="java-release-source-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}"
          mkdir -p "$handoff_dir"
          git -C "$GITHUB_WORKSPACE" bundle create --version=2 "$bundle" --all "$SOURCE_COMMIT"
          git -C "$GITHUB_WORKSPACE" bundle verify "$bundle"
          bundle_sha256="$(sha256sum "$bundle" | awk '{print $1}')"
          jq -n \
            --arg run_id "$GITHUB_RUN_ID" \
            --arg run_attempt "$GITHUB_RUN_ATTEMPT" \
            --arg source_commit "$SOURCE_COMMIT" \
            --arg bundle_sha256 "$bundle_sha256" \
            --arg artifact_name "$artifact_name" \
            '{run_id: $run_id, run_attempt: $run_attempt, source_commit: $source_commit, bundle_sha256: $bundle_sha256, bundle_format: "git-bundle-v2", artifact_name: $artifact_name}' \
            > "$metadata"
          {
            echo "artifact_name=$artifact_name"
            echo "bundle_sha256=$bundle_sha256"
          } >> "$GITHUB_OUTPUT"

      - name: Upload release source handoff
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: ${{ steps.release-source-handoff.outputs.artifact_name }}
          path: |
            ${{ runner.temp }}/release-source/release.bundle
            ${{ runner.temp }}/release-source/release-metadata.json
          if-no-files-found: error
          retention-days: 14

  build-distributions:
    name: Build ${{ matrix.release.tag }}
    needs: prepare-release
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    strategy:
      fail-fast: false
      matrix:
        release: ${{ fromJSON(needs.prepare-release.outputs.releases) }}
    steps:
      - name: Download release source handoff
        env:
          EXPECTED_ARTIFACT: ${{ needs.prepare-release.outputs.release_source_artifact }}
          GH_TOKEN: ${{ github.token }}
        shell: bash
        run: |
          set -euo pipefail
          gh run download "$GITHUB_RUN_ID" \
            --repo "$GITHUB_REPOSITORY" \
            --name "$EXPECTED_ARTIFACT" \
            --dir "$RUNNER_TEMP/release-source"

      - name: Verify and materialize release source
        env:
          EXPECTED_RUN_ID: ${{ github.run_id }}
          EXPECTED_RUN_ATTEMPT: ${{ github.run_attempt }}
          EXPECTED_SOURCE_COMMIT: ${{ needs.prepare-release.outputs.release_commit }}
          EXPECTED_BUNDLE_SHA256: ${{ needs.prepare-release.outputs.release_source_sha256 }}
          EXPECTED_ARTIFACT: ${{ needs.prepare-release.outputs.release_source_artifact }}
        shell: bash
        run: |
          set -euo pipefail
          bundle="$RUNNER_TEMP/release-source/release.bundle"
          metadata="$RUNNER_TEMP/release-source/release-metadata.json"
          if [[ ! -f "$bundle" || ! -f "$metadata" ]] \
            || [[ ! "$EXPECTED_SOURCE_COMMIT" =~ ^[0-9a-f]{40}$ ]] \
            || [[ ! "$EXPECTED_BUNDLE_SHA256" =~ ^[0-9a-f]{64}$ ]]; then
            echo "::error title=Invalid release source handoff::The release bundle or its immutable metadata is missing." >&2
            exit 1
          fi
          if ! jq -e \
            --arg run_id "$EXPECTED_RUN_ID" \
            --arg run_attempt "$EXPECTED_RUN_ATTEMPT" \
            --arg source_commit "$EXPECTED_SOURCE_COMMIT" \
            --arg bundle_sha256 "$EXPECTED_BUNDLE_SHA256" \
            --arg artifact_name "$EXPECTED_ARTIFACT" \
            'type == "object" and .run_id == $run_id and .run_attempt == $run_attempt and .source_commit == $source_commit and .bundle_sha256 == $bundle_sha256 and .bundle_format == "git-bundle-v2" and .artifact_name == $artifact_name' \
            "$metadata" > /dev/null; then
            echo "::error title=Invalid release source handoff::Release source metadata does not match this run." >&2
            exit 1
          fi
          actual_bundle_sha256="$(sha256sum "$bundle" | awk '{print $1}')"
          if [[ "$actual_bundle_sha256" != "$EXPECTED_BUNDLE_SHA256" ]]; then
            echo "::error title=Release source digest mismatch::The downloaded release bundle does not match its prepared digest." >&2
            exit 1
          fi
          verifier="$RUNNER_TEMP/release-source-verifier"
          git init --quiet "$verifier"
          if find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -print -quit | grep -q .; then
            echo "::error title=Unexpected release workspace::Build distributions requires an empty workspace before materializing the handoff." >&2
            exit 1
          fi
          git -C "$verifier" bundle verify "$bundle"
          git clone --no-checkout "$bundle" "$GITHUB_WORKSPACE"
          git -C "$GITHUB_WORKSPACE" checkout --detach "$EXPECTED_SOURCE_COMMIT"
          if [[ "$(git -C "$GITHUB_WORKSPACE" rev-parse HEAD)" != "$EXPECTED_SOURCE_COMMIT" ]]; then
            echo "::error title=Release source commit mismatch::The materialized source is not the prepared release commit." >&2
            exit 1
          fi

      - name: Resolve governed project type
        shell: bash
        run: |
          set -euo pipefail
          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          if [[ ! -f "$descriptor" ]]; then
            echo "::error title=Missing descriptor::.github/inditextech-ci-java.json not found."
            exit 1
          fi
          project_type="$(jq -r '.project_type // empty' "$descriptor")"
          case "$project_type" in
            single|monorepo) ;;
            *)
              echo "::error title=Invalid project type::Descriptor .project_type must be single or monorepo."
              exit 1
              ;;
          esac
          workdir="${WORKING_DIRECTORY:-$(jq -r '.working_directory // empty' "$descriptor")}"
          case "$workdir" in
            ""|/*|..|../*|*/..|*/../*)
              echo "::error title=Invalid working directory::WORKING_DIRECTORY must be a non-empty relative repository path." >&2
              exit 1
              ;;
          esac
          if [[ ! -d "$workdir" ]]; then
            echo "::error title=Missing working directory::'${workdir}' is not a directory in this checkout." >&2
            exit 1
          fi
          echo "WORKING_DIRECTORY=${workdir}" >> "$GITHUB_ENV"
          echo "PROJECT_TYPE=$project_type" >> "$GITHUB_ENV"

      - name: Set up workflow Java
        uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
        with:
          distribution: temurin
          java-version: '25.0.2+10.0.LTS'
          cache: maven
          cache-dependency-path: ${{ env.WORKING_DIRECTORY }}/**/pom.xml

      - name: Read governed tool versions
        id: tool-versions
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if grep -Evq '^[a-zA-Z0-9_-]+ [a-zA-Z0-9._+-]+$' .tool-versions; then
            echo "::error title=Invalid tool-versions::${WORKING_DIRECTORY}/.tool-versions is malformed."
            exit 1
          fi
          {
            echo "tool_versions<<EOF"
            cat .tool-versions
            echo
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Set up asdf-managed Java
        uses: asdf-vm/actions/install@b7bcd026f18772e44fe1026d729e1611cc435d47 # v4.0.1
        with:
          tool_versions: ${{ steps.tool-versions.outputs.tool_versions }}
          asdf_version: ${{ env.ASDF_BRANCH_VERSION }}

      - name: Resolve build JDK from .tool-versions
        id: jdk
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          echo "java_home=$(asdf where java)" >> "$GITHUB_OUTPUT"

      - name: Build declared artifacts
        env:
          JAVA_HOME: ${{ steps.jdk.outputs.java_home }}
          RELEASE: ${{ toJSON(matrix.release) }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          dist="$RUNNER_TEMP/dist"
          rm -rf "$dist"
          mkdir -p "$dist"
          mvn -B --no-transfer-progress -f pom.xml -DskipTests -DskipEnforceSnapshots clean package

          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          declared="$(jq -r '.release.artifacts // [] | .[]' "$descriptor")"
          artifact_ids="$(jq -c '.packages' <<< "$RELEASE")"
          if [[ "$PROJECT_TYPE" == "monorepo" ]] \
            && [[ "$(jq -r 'length' <<< "$artifact_ids")" -eq 0 ]] \
            && [[ "$(jq -r '.release.strategy // empty' "$descriptor")" == "locked-step" ]]; then
            artifact_ids="$(jq -c '[(.release.packages // [])[] | ascii_downcase
              | gsub("[^a-z0-9]+"; "-") | gsub("^-+|-+$"; "")]' "$descriptor")"
          fi

          is_release_distribution() {
            case "$(basename "$1")" in
              *-tests.jar|*-sources.jar|*-javadoc.jar) return 1 ;;
            esac
            [[ -f "$1" && "$1" == *.jar ]]
          }

          if [[ -n "$declared" ]]; then
            shopt -s nullglob
            root="$PWD"
            while IFS= read -r pattern; do
              [[ -n "$pattern" ]] || continue
              case "$pattern" in
                /*|*'**'*|*..*)
                  echo "::error title=Invalid release artifact::release.artifacts entry '$pattern' must be a relative path inside the working directory, without '..' or '**'."
                  exit 1
                  ;;
              esac
              saved_ifs="$IFS"
              IFS=
              # shellcheck disable=SC2206
              matches=($pattern)
              IFS="$saved_ifs"
              selected=0
              for match in ${matches[@]+"${matches[@]}"}; do
                [[ -f "$match" && "$match" == *.jar ]] || continue
                resolved="$(cd "$(dirname "$match")" && pwd -P)/$(basename "$match")"
                case "$resolved" in
                  "$root"/*) ;;
                  *)
                    echo "::error title=Invalid release artifact::release.artifacts entry '$pattern' resolved outside the working directory."
                    exit 1
                    ;;
                esac
                cp "$resolved" "$dist"/
                selected=$((selected + 1))
              done
              if [[ "$selected" -eq 0 ]]; then
                echo "::error title=Unmatched release artifact::release.artifacts entry '$pattern' matched no jar."
                exit 1
              fi
            done <<< "$declared"
          elif [[ "$(jq -r 'length' <<< "$artifact_ids")" -gt 0 ]]; then
            release_version="$(jq -r '.version // .tag' <<< "$RELEASE")"
            while IFS= read -r module; do
              [[ -n "$module" ]] || continue
              selected=0
              # Select the module JAR by Maven artifactId at arbitrary depth.
              while IFS= read -r jar; do
                is_release_distribution "$jar" || continue
                cp "$jar" "$dist"/
                selected=$((selected + 1))
              done < <(find . -type f \
                -path "*/target/${module}-${release_version}.jar")
              if [[ "$selected" -eq 0 ]]; then
                echo "::error title=Undeclared release artifacts::Module '$module' is published but produced no ${module}-${release_version}.jar, so the assets to attach cannot be inferred. Declare release.artifacts in .github/inditextech-ci-java.json."
                exit 1
              fi
            done < <(jq -r '.[]' <<< "$artifact_ids")
          elif [[ "$PROJECT_TYPE" == "single" ]]; then
            cp target/*.jar "$dist"/ 2>/dev/null || true
            if ! ls "$dist"/*.jar > /dev/null 2>&1; then
              while IFS= read -r jar; do
                is_release_distribution "$jar" || continue
                cp "$jar" "$dist"/ 2>/dev/null || true
              done < <(find . -type f -name '*.jar' -path '*/target/*' ! -path '*/target/*/*')
            fi
          else
            echo "::error title=Undeclared release artifacts::This reactor publishes no package list, so the jars to attach cannot be inferred. Declare release.artifacts in .github/inditextech-ci-java.json."
            exit 1
          fi

          if ! ls "$dist"/*.jar > /dev/null 2>&1; then
            echo "::error title=Missing artifacts::No jars were produced for ${RELEASE}."
            exit 1
          fi

      - name: Upload release artifacts
        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
        with:
          name: java-distributions-${{ matrix.release.tag }}
          path: ${{ runner.temp }}/dist/*
          if-no-files-found: error
          retention-days: 14

  finalize-release:
    name: Finalize release (promote + next dev)
    if: inputs.phase == 'finalize' && inputs.promote
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Check out repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Create GitHub App token
        id: app-token
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          permission-contents: write
          permission-pull-requests: write

      - name: Check out release branch
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.event.pull_request.base.ref || github.ref_name }}
          token: ${{ steps.app-token.outputs.token }}

      - name: Resolve governed project type
        shell: bash
        run: |
          set -euo pipefail
          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          if [[ ! -f "$descriptor" ]]; then
            echo "::error title=Missing descriptor::.github/inditextech-ci-java.json not found."
            exit 1
          fi
          project_type="$(jq -r '.project_type // empty' "$descriptor")"
          case "$project_type" in
            single|monorepo) ;;
            *)
              echo "::error title=Invalid project type::Descriptor .project_type must be single or monorepo."
              exit 1
              ;;
          esac
          workdir="${WORKING_DIRECTORY:-$(jq -r '.working_directory // empty' "$descriptor")}"
          case "$workdir" in
            ""|/*|..|../*|*/..|*/../*)
              echo "::error title=Invalid working directory::WORKING_DIRECTORY must be a non-empty relative repository path." >&2
              exit 1
              ;;
          esac
          if [[ ! -d "$workdir" ]]; then
            echo "::error title=Missing working directory::'${workdir}' is not a directory in this checkout." >&2
            exit 1
          fi
          echo "WORKING_DIRECTORY=${workdir}" >> "$GITHUB_ENV"
          echo "PROJECT_TYPE=$project_type" >> "$GITHUB_ENV"

      - name: Set up workflow Java
        uses: actions/setup-java@de7274f081f381c8f8158605e0321c36c376e2e6 # v6.0.1
        with:
          distribution: temurin
          java-version: '25.0.2+10.0.LTS'
          cache: maven
          cache-dependency-path: ${{ env.WORKING_DIRECTORY }}/**/pom.xml

      - name: Read governed tool versions
        id: tool-versions
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if grep -Evq '^[a-zA-Z0-9_-]+ [a-zA-Z0-9._+-]+$' .tool-versions; then
            echo "::error title=Invalid tool-versions::${WORKING_DIRECTORY}/.tool-versions is malformed."
            exit 1
          fi
          {
            echo "tool_versions<<EOF"
            cat .tool-versions
            echo
            echo "EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Set up asdf-managed Java
        uses: asdf-vm/actions/install@b7bcd026f18772e44fe1026d729e1611cc435d47 # v4.0.1
        with:
          tool_versions: ${{ steps.tool-versions.outputs.tool_versions }}
          asdf_version: ${{ env.ASDF_BRANCH_VERSION }}

      - name: Resolve build JDK from .tool-versions
        id: jdk
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          echo "java_home=$(asdf where java)" >> "$GITHUB_OUTPUT"

      - name: Promote the release to the default branch
        id: promote
        env:
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          EXPECTED_REF: ${{ inputs.expected_ref }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASES: ${{ inputs.releases }}
          RELEASE_COMMIT: ${{ inputs.release_commit }}
          PROMOTE_COMMIT: ${{ inputs.promote_commit }}
          STAGING_REF: ${{ inputs.staging_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          gh auth setup-git
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"

          git fetch --no-tags origin "+${STAGING_REF}:refs/ci-governance/staged" 2>/dev/null || true
          if [[ "$(git ls-remote origin "$EXPECTED_REF" | cut -f1)" == "$PROMOTE_COMMIT" ]]; then
            echo "::notice title=Promotion skipped::$EXPECTED_REF already points at the release commit."
            git checkout --force --detach "$RELEASE_COMMIT"
            exit 0
          fi

          if [[ "$(git rev-parse --verify --quiet refs/ci-governance/staged || true)" != "$PROMOTE_COMMIT" ]]; then
            echo "::error title=Release staging mismatch::$STAGING_REF does not point at the release commit."
            exit 1
          fi
          git checkout --force --detach "$RELEASE_COMMIT"

          tag_refs=()
          while IFS= read -r record; do
            tag="$(jq -r '.tag' <<< "$record")"
            version="$(jq -r '.version' <<< "$record")"
            git check-ref-format --allow-onelevel "refs/tags/$tag"
            if git ls-remote --exit-code --tags origin "refs/tags/$tag" >/dev/null 2>&1; then
              echo "::error title=Tag conflict::$tag already exists."
              exit 1
            fi
            git tag -a "$tag" -m "Release $version" "$RELEASE_COMMIT"
            tag_refs+=("refs/tags/$tag")
          done < <(jq -c '.[]' <<< "$RELEASES")

          git push --atomic origin "${PROMOTE_COMMIT}:${EXPECTED_REF}" "${tag_refs[@]}"

      - name: Next development iteration and sync PR
        if: steps.promote.outcome == 'success'
        env:
          JAVA_HOME: ${{ steps.jdk.outputs.java_home }}
          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
          BASELINE_BRANCH: ${{ github.event.pull_request.base.ref || github.ref_name }}
          DEVELOPMENT_FLOW: ${{ vars.DEVELOPMENT_FLOW }}
          GIT_FLOW_RELEASE_BRANCH: ${{ vars.GIT_FLOW_RELEASE_BRANCH }}
          GIT_FLOW_DEVELOPMENT_BRANCH: ${{ vars.GIT_FLOW_DEVELOPMENT_BRANCH }}
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          RELEASES: ${{ inputs.releases }}
          RELEASE_COMMIT: ${{ inputs.release_commit }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          gh auth setup-git
          git config user.name "${APP_SLUG}[bot]"
          git config user.email "${APP_SLUG}[bot]@users.noreply.github.com"

          descriptor="$GITHUB_WORKSPACE/.github/inditextech-ci-java.json"
          release_mode="$(jq -r '.release.lifecycle // "govern-inject"' "$descriptor")"

          if [[ "$release_mode" == "delegated" ]]; then
            echo "::notice title=Next-dev skipped::Delegated release already advanced next development."
          elif [[ "$(git rev-parse HEAD)" != "$RELEASE_COMMIT" ]]; then
            echo "::notice title=Next-dev skipped::Branch already advanced past the release commit."
          else
            if [[ "$PROJECT_TYPE" == "single" ]]; then
              next_dev="$(jq -r '.[0].next_dev' <<< "$RELEASES")"
              mvn -q -B --no-transfer-progress -f pom.xml versions:set \
                -DnewVersion="$next_dev" -DgenerateBackupPoms=false
            elif [[ "$(jq -er '.release.strategy' "$descriptor")" == "locked-step" ]]; then
              next_dev="$(jq -r '.[0].next_dev' <<< "$RELEASES")"
              mvn -q -B --no-transfer-progress -f pom.xml versions:set \
                -DnewVersion="$next_dev" -DprocessAllModules=true -DgenerateBackupPoms=false
            else
              while IFS= read -r record; do
                artifact="$(jq -r '.packages[0]' <<< "$record")"
                next_dev="$(jq -r '.next_dev' <<< "$record")"
                mvn -q -B --no-transfer-progress -f pom.xml versions:set \
                  -DgroupId=com.inditextech -DartifactId="$artifact" -DoldVersion='*' \
                  -DnewVersion="$next_dev" -DprocessAllModules=false -DgenerateBackupPoms=false
              done < <(jq -c '.[]' <<< "$RELEASES")
            fi
            git -C "$GITHUB_WORKSPACE" add --update -- "$WORKING_DIRECTORY"
            git commit -m "[java-release] prepare for next development iteration"
            git push origin "HEAD:refs/heads/$BASELINE_BRANCH"
          fi

          if [[ "$DEVELOPMENT_FLOW" != "git-flow" ]]; then
            echo "::notice title=Sync skipped::Sync-to-develop applies only to git-flow."
            exit 0
          fi

          version="$(jq -r '.[0].version' <<< "$RELEASES")"
          if [[ -z "$GIT_FLOW_RELEASE_BRANCH" || -z "$GIT_FLOW_DEVELOPMENT_BRANCH" ]]; then
            echo "::error title=Missing git-flow branch roles::GIT_FLOW_RELEASE_BRANCH and GIT_FLOW_DEVELOPMENT_BRANCH are required for git-flow release synchronization."
            exit 1
          fi
          if [[ "$BASELINE_BRANCH" == "$GIT_FLOW_RELEASE_BRANCH" ]]; then
            develop_branch="$GIT_FLOW_DEVELOPMENT_BRANCH"
          elif [[ "$BASELINE_BRANCH" == "$GIT_FLOW_RELEASE_BRANCH"-* && "$BASELINE_BRANCH" != "$GIT_FLOW_RELEASE_BRANCH"- ]]; then
            develop_branch="${GIT_FLOW_DEVELOPMENT_BRANCH}${BASELINE_BRANCH#"$GIT_FLOW_RELEASE_BRANCH"}"
          else
            echo "::error title=Invalid release branch::${BASELINE_BRANCH} is not a configured release branch."
            exit 1
          fi
          if [[ -z "$(git ls-remote --heads origin "$develop_branch")" ]]; then
            echo "::notice title=Sync skipped::$develop_branch does not exist."
            exit 0
          fi
          sync_branch="automated/sync-release-${version}-to-${develop_branch}"
          git switch --force-create "$sync_branch" "origin/$BASELINE_BRANCH"
          git push --force-with-lease --set-upstream origin "$sync_branch"

          if [[ -z "$(gh pr list --repo "$GITHUB_REPOSITORY" --head "$sync_branch" --base "$develop_branch" --state open --json number --jq '.[0].number // empty')" ]]; then
            gh pr create --repo "$GITHUB_REPOSITORY" \
              --base "$develop_branch" --head "$sync_branch" \
              --title "Sync release $version to $develop_branch" \
              --body "**Automated pull request** syncing the release cut on \`$BASELINE_BRANCH\` back into \`$develop_branch\`."
          fi

      - name: Discard the release staging ref
        if: always()
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          STAGING_REF: ${{ inputs.staging_ref }}
          STAGED_TAG_REF: ${{ inputs.staged_tag_ref }}
        working-directory: ${{ env.WORKING_DIRECTORY }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ -z "${STAGING_REF:-}" ]]; then
            exit 0
          fi
          gh auth setup-git
          refs=(":${STAGING_REF}")
          if [[ -n "${STAGED_TAG_REF:-}" ]]; then
            refs+=(":${STAGED_TAG_REF}")
          fi
          git push origin "${refs[@]}"

  discard-unbuilt-staging:
    name: Discard failed build staging refs
    needs: [prepare-release, build-distributions]
    if: >-
      !cancelled() &&
      inputs.phase == 'prepare' &&
      needs.prepare-release.result == 'success' &&
      needs.build-distributions.result != 'success'
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Check out repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Create GitHub App token
        id: app-token
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          permission-contents: write

      - name: Discard the release staging ref
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          STAGING_REF: ${{ needs.prepare-release.outputs.staging_ref }}
          STAGED_TAG_REF: ${{ needs.prepare-release.outputs.staged_tag_ref }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ -z "${STAGING_REF:-}" ]]; then
            exit 0
          fi
          gh auth setup-git
          refs=(":${STAGING_REF}")
          if [[ -n "${STAGED_TAG_REF:-}" ]]; then
            refs+=(":${STAGED_TAG_REF}")
          fi
          git -C "$GITHUB_WORKSPACE" push origin "${refs[@]}"

  discard-unpublished-staging:
    name: Discard unpublished staging refs
    if: inputs.phase == 'finalize' && !inputs.promote
    runs-on: ubuntu-24.04
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - name: Check out repository
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false

      - name: Create GitHub App token
        id: app-token
        uses: actions/create-github-app-token@64ab729a6294000f5aa4a4bc0b73d1f32bc45510 # v3.3.0
        with:
          client-id: ${{ vars.APP_CLIENT_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          permission-contents: write

      - name: Discard the release staging ref
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          STAGING_REF: ${{ inputs.staging_ref }}
          STAGED_TAG_REF: ${{ inputs.staged_tag_ref }}
        shell: bash
        run: |
          set -euo pipefail
          if [[ -z "${STAGING_REF:-}" ]]; then
            exit 0
          fi
          gh auth setup-git
          refs=(":${STAGING_REF}")
          if [[ -n "${STAGED_TAG_REF:-}" ]]; then
            refs+=(":${STAGED_TAG_REF}")
          fi
          git -C "$GITHUB_WORKSPACE" push origin "${refs[@]}"