release-android.yml

# Hermes-Relay Android — Release Pipeline
#
# Triggered when an Android release tag (android-v*) is pushed.
# Validates the tag matches the app version in libs.versions.toml,
# runs focused Android checks, builds release APK/AAB artifacts, and creates a
# GitHub Release. Plugin/Python package releases use server-v* tags.

name: Hermes-Relay Android Release

on:
  push:
    tags:
      - "android-v*"
  # Hermes-Relay Android Release Approval creates its tag with GITHUB_TOKEN,
  # whose tag event
  # does not recursively start workflows. It dispatches the current workflow
  # definition from main, while every job checks out the immutable tag. Manual
  # tag pushes continue to use the push trigger.
  workflow_dispatch:
    inputs:
      version:
        description: "Approved Android version"
        required: true
        type: string

permissions:
  contents: write
  actions: read
  id-token: write

jobs:
  validate:
    name: Validate Release
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
      version_code: ${{ steps.version.outputs.version_code }}
      prerelease: ${{ steps.version.outputs.prerelease }}
      release_tree: ${{ steps.version.outputs.release_tree }}
      preflight_artifact_id: ${{ steps.preflight.outputs.artifact_id }}
      preflight_run_id: ${{ steps.preflight.outputs.run_id }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ github.event_name == 'workflow_dispatch' && format('android-v{0}', inputs.version) || github.ref }}

      - name: Extract version from tag
        id: version
        env:
          DISPATCHED_VERSION: ${{ inputs.version }}
        run: |
          if [ -n "$DISPATCHED_VERSION" ]; then
            REF_VERSION="$DISPATCHED_VERSION"
            TAG_COMMIT=$(git rev-list -n 1 "android-v${REF_VERSION}")
            if [ -z "$TAG_COMMIT" ] || [ "$TAG_COMMIT" != "$(git rev-parse HEAD)" ]; then
              echo "::error::Checked-out commit does not match immutable tag android-v${REF_VERSION}"
              exit 1
            fi
          else
            REF_VERSION="${GITHUB_REF#refs/tags/android-v}"
          fi
          VERSION_CODE=$(grep -oP 'appVersionCode\s*=\s*"\K[^"]+' gradle/libs.versions.toml)
          if [[ "$REF_VERSION" == *-* ]]; then
            PRERELEASE=true
          else
            PRERELEASE=false
          fi
          echo "version=$REF_VERSION" >> "$GITHUB_OUTPUT"
          echo "version_code=$VERSION_CODE" >> "$GITHUB_OUTPUT"
          echo "prerelease=$PRERELEASE" >> "$GITHUB_OUTPUT"
          echo "release_tree=$(git rev-parse 'HEAD^{tree}')" >> "$GITHUB_OUTPUT"

      - name: Verify version sync
        run: |
          TAG_VERSION="${{ steps.version.outputs.version }}"
          TOML_VERSION=$(grep -oP 'appVersionName\s*=\s*"\K[^"]+' gradle/libs.versions.toml)

          echo "Tag version: $TAG_VERSION"
          echo "libs.versions.toml version: $TOML_VERSION"

          if [ "$TAG_VERSION" != "$TOML_VERSION" ]; then
            echo "::error::Tag version ($TAG_VERSION) does not match appVersionName ($TOML_VERSION) in gradle/libs.versions.toml"
            exit 1
          fi
          if ! grep -Eq "^## \\[(Android )?${TAG_VERSION}\\]" CHANGELOG.md; then
            echo "::error::CHANGELOG.md has no Android release heading for $TAG_VERSION"
            exit 1
          fi

          echo "Version validated: $TAG_VERSION"

      - name: Verify public privacy policy URLs
        run: python3 scripts/check-privacy-policy.py --live

      - name: Verify tag belongs to the correct integration branch
        env:
          PRERELEASE: ${{ steps.version.outputs.prerelease }}
        run: |
          set -euo pipefail
          tag_commit="$(git rev-parse HEAD)"
          if [ "$PRERELEASE" = "true" ]; then
            git fetch origin dev --no-tags
            if ! git merge-base --is-ancestor "$tag_commit" origin/dev; then
              echo "Android prereleases must be tagged from dev; $tag_commit is not in origin/dev" >&2
              exit 1
            fi
          else
            git fetch origin main --no-tags
            if ! git merge-base --is-ancestor "$tag_commit" origin/main; then
              echo "Stable Android releases must be tagged from main; $tag_commit is not in origin/main" >&2
              exit 1
            fi
          fi

      - name: Require successful Play preflight for this exact release tree
        id: preflight
        if: ${{ !contains(steps.version.outputs.version, '-') }}
        env:
          GH_TOKEN: ${{ github.token }}
          VERSION: ${{ steps.version.outputs.version }}
        run: |
          RELEASE_TREE="${{ steps.version.outputs.release_tree }}"
          ARTIFACT_NAME="play-preflight-${VERSION}-${RELEASE_TREE}"
          ARTIFACT=$(gh api "/repos/${GITHUB_REPOSITORY}/actions/artifacts?name=${ARTIFACT_NAME}" \
            --jq '[.artifacts[] | select(.expired == false)] | sort_by(.created_at) | last')
          ARTIFACT_ID=$(jq -r '.id // empty' <<<"$ARTIFACT")
          RUN_ID=$(jq -r '.workflow_run.id // empty' <<<"$ARTIFACT")
          if [ -z "$ARTIFACT_ID" ] || [ -z "$RUN_ID" ]; then
            echo "::error::No successful Play preflight found for version $VERSION with tree $RELEASE_TREE"
            echo "Run Hermes-Relay Android Play Preflight from the final dev tree, merge that unchanged tree to main, then approve the release."
            exit 1
          fi
          RUN=$(gh api "/repos/${GITHUB_REPOSITORY}/actions/runs/${RUN_ID}")
          CONCLUSION=$(jq -r '.conclusion' <<<"$RUN")
          WORKFLOW_PATH=$(jq -r '.path' <<<"$RUN")
          if [ "$WORKFLOW_PATH" != ".github/workflows/play-preflight-android.yml" ] || [ "$CONCLUSION" != "success" ]; then
            echo "::error::Preflight artifact came from ${WORKFLOW_PATH} with conclusion ${CONCLUSION}"
            exit 1
          fi
          echo "artifact_id=$ARTIFACT_ID" >> "$GITHUB_OUTPUT"
          echo "run_id=$RUN_ID" >> "$GITHUB_OUTPUT"
          echo "Play preflight artifacts verified: $ARTIFACT_NAME (run $RUN_ID, artifact $ARTIFACT_ID)"

  ci:
    name: CI Checks (prerelease only)
    needs: validate
    if: ${{ needs.validate.outputs.prerelease == 'true' }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && format('android-v{0}', inputs.version) || github.ref }}

      - name: Set up JDK 17
        uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: 17

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v6.4.0
        with:
          cache-read-only: false

      - name: Validate release metadata and Android API compatibility
        run: |
          python3 scripts/check-version-tracks.py
          python3 scripts/check-android-release-notes.py
          python3 scripts/check-privacy-policy.py
          python3 scripts/check-android-locales.py
          python3 scripts/check-android-collection-apis.py

      # Keep the tag release gate aligned with CI — Android's broad Gradle
      # `test` aggregate currently hangs in deferred JVM suites tracked by
      # issue #32, so the release gate runs the stable connection/pairing slice.
      - name: Run focused Android unit tests
        run: |
          ./gradlew :app:testSideloadDebugUnitTest \
            --tests com.hermesandroid.relay.network.RelayUrlDeriverTest \
            --tests com.hermesandroid.relay.viewmodel.ConnectionSwitchTest \
            --console=plain

  release:
    name: Build & Publish Release
    needs: [validate, ci]
    if: ${{ always() && needs.validate.result == 'success' && (needs.ci.result == 'success' || needs.ci.result == 'skipped') }}
    runs-on: ubuntu-latest
    timeout-minutes: 30
    steps:
      - uses: actions/checkout@v7
        with:
          ref: ${{ github.event_name == 'workflow_dispatch' && format('android-v{0}', inputs.version) || github.ref }}

      - name: Set up JDK 17
        uses: actions/setup-java@v6
        with:
          distribution: temurin
          java-version: 17

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v6.4.0
        with:
          cache-read-only: false

      - name: Download exact stable preflight artifacts
        if: ${{ needs.validate.outputs.prerelease != 'true' }}
        uses: actions/download-artifact@v8
        with:
          artifact-ids: ${{ needs.validate.outputs.preflight_artifact_id }}
          github-token: ${{ github.token }}
          repository: ${{ github.repository }}
          run-id: ${{ needs.validate.outputs.preflight_run_id }}
          path: app/build/preflight-artifacts

      - name: Verify exact stable preflight artifacts
        if: ${{ needs.validate.outputs.prerelease != 'true' }}
        run: |
          python3 scripts/android_release_artifacts.py verify \
            --version "${{ needs.validate.outputs.version }}" \
            --version-code "${{ needs.validate.outputs.version_code }}" \
            --tree "${{ needs.validate.outputs.release_tree }}" \
            --directory app/build/preflight-artifacts

      - name: Decode release keystore for candidate build
        env:
          HERMES_KEYSTORE_BASE64: ${{ secrets.HERMES_KEYSTORE_BASE64 }}
        if: ${{ needs.validate.outputs.prerelease == 'true' && env.HERMES_KEYSTORE_BASE64 != '' }}
        run: |
          echo "$HERMES_KEYSTORE_BASE64" | base64 -d > "$RUNNER_TEMP/release.keystore"
          echo "HERMES_KEYSTORE_PATH=$RUNNER_TEMP/release.keystore" >> "$GITHUB_ENV"

      - name: Build side-by-side release candidate APK
        if: ${{ needs.validate.outputs.prerelease == 'true' }}
        env:
          HERMES_KEYSTORE_PASSWORD: ${{ secrets.HERMES_KEYSTORE_PASSWORD }}
          HERMES_KEY_ALIAS: ${{ secrets.HERMES_KEY_ALIAS }}
          HERMES_KEY_PASSWORD: ${{ secrets.HERMES_KEY_PASSWORD }}
          VERSION: ${{ needs.validate.outputs.version }}
        run: |
          SOURCE_SHA="$(git rev-parse HEAD)"
          ./gradlew :app:assembleSideloadCandidate \
            -Pcandidate.kind=rc \
            -Pcandidate.label="Hermes-Relay Android v${VERSION}" \
            -Pcandidate.sourceRef="android-v${VERSION}" \
            -Pcandidate.sourceSha="$SOURCE_SHA" \
            --console=plain

      # The Play AAB carries its mapping for Play Console deobfuscation, but
      # sideload issue reports need the exact mapping from this immutable build.
      # Keep both variants as a workflow artifact (not a public release asset).
      - name: Retain R8 mappings for retrace
        if: ${{ needs.validate.outputs.prerelease != 'true' }}
        uses: actions/upload-artifact@v7
        with:
          name: android-r8-mappings-${{ needs.validate.outputs.version }}-${{ needs.validate.outputs.release_tree }}
          path: |
            app/build/preflight-artifacts/mapping-googlePlayRelease.txt
            app/build/preflight-artifacts/mapping-sideloadRelease.txt
          if-no-files-found: error
          retention-days: 90

      - name: Retain candidate R8 mapping for retrace
        if: ${{ needs.validate.outputs.prerelease == 'true' }}
        uses: actions/upload-artifact@v7
        with:
          name: android-rc-r8-mapping-${{ needs.validate.outputs.version }}-${{ github.sha }}
          path: app/build/outputs/mapping/sideloadCandidate/mapping.txt
          if-no-files-found: error
          retention-days: 90

      - name: Scan stable release DEX for unsupported collection APIs
        if: ${{ needs.validate.outputs.prerelease != 'true' }}
        run: |
          python3 scripts/check-android-collection-apis.py \
            --apk app/build/preflight-artifacts/*-sideload-release.apk

      - name: Scan candidate DEX for unsupported collection APIs
        if: ${{ needs.validate.outputs.prerelease == 'true' }}
        run: |
          python3 scripts/check-android-collection-apis.py \
            --apk app/build/outputs/apk/sideload/candidate/*.apk

      - name: Verify stable packaged ONNX Runtime compatibility
        if: ${{ needs.validate.outputs.prerelease != 'true' }}
        run: |
          python3 scripts/check-android-native-compat.py \
            app/build/preflight-artifacts/*-sideload-release.apk

      - name: Verify candidate packaged ONNX Runtime compatibility
        if: ${{ needs.validate.outputs.prerelease == 'true' }}
        run: |
          python3 scripts/check-android-native-compat.py \
            app/build/outputs/apk/sideload/candidate/*.apk

      - name: List produced artifacts (debug aid)
        run: |
          echo "=== Reused stable artifacts ==="
          find app/build/preflight-artifacts -maxdepth 1 -type f -print 2>/dev/null || true
          echo "=== Candidate APK outputs ==="
          find app/build/outputs/apk -name '*.apk' -print 2>/dev/null || true

      - name: Generate candidate checksums
        if: ${{ needs.validate.outputs.prerelease == 'true' }}
        run: |
          cd app/build/outputs
          sha256sum apk/sideload/candidate/*.apk > SHA256SUMS.txt
          cat SHA256SUMS.txt

      - name: Require Play credentials for stable release
        env:
          PLAY_SERVICE_ACCOUNT_JSON: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
        if: ${{ !contains(needs.validate.outputs.version, '-') }}
        run: |
          if [ -z "$PLAY_SERVICE_ACCOUNT_JSON" ]; then
            echo "::error::PLAY_SERVICE_ACCOUNT_JSON is required for stable Android releases"
            exit 1
          fi

      - name: Submit preflighted Play draft to production review
        env:
          PLAY_SERVICE_ACCOUNT_JSON: ${{ secrets.PLAY_SERVICE_ACCOUNT_JSON }}
        if: ${{ !contains(needs.validate.outputs.version, '-') }}
        run: |
          trap 'rm -f play-service-account.json' EXIT
          printf '%s' "$PLAY_SERVICE_ACCOUNT_JSON" > play-service-account.json
          ./gradlew promoteGooglePlayReleaseArtifact \
            --update=production \
            --version-code=${{ needs.validate.outputs.version_code }} \
            --release-status=completed \
            --release-name="Hermes-Relay Android v${{ needs.validate.outputs.version }}"

      # Public distribution happens only after Play accepts the production
      # submission above. This keeps a Play-detected release blocker from
      # appearing after the sideload APK is already public.
      - name: Create stable GitHub Release
        if: ${{ needs.validate.outputs.prerelease != 'true' }}
        uses: softprops/action-gh-release@v3
        with:
          name: Hermes-Relay Android v${{ needs.validate.outputs.version }}
          tag_name: android-v${{ needs.validate.outputs.version }}
          body_path: RELEASE_NOTES.md
          prerelease: false
          # Deliberate 2-asset policy (#144): attach ONLY the installable
          # sideload APK and Play AAB, plus checksums covering those files.
          files: |
            app/build/preflight-artifacts/*-sideload-release.apk
            app/build/preflight-artifacts/*-googlePlay-release.aab
            app/build/preflight-artifacts/SHA256SUMS.txt

      - name: Create candidate GitHub prerelease
        if: ${{ needs.validate.outputs.prerelease == 'true' }}
        uses: softprops/action-gh-release@v3
        with:
          name: Hermes-Relay Android v${{ needs.validate.outputs.version }}
          tag_name: android-v${{ needs.validate.outputs.version }}
          body_path: RELEASE_NOTES.md
          prerelease: true
          fail_on_unmatched_files: true
          files: |
            app/build/outputs/apk/sideload/candidate/*.apk
            app/build/outputs/SHA256SUMS.txt

      - name: Release summary
        env:
          HERMES_KEYSTORE_BASE64: ${{ secrets.HERMES_KEYSTORE_BASE64 }}
          PRERELEASE: ${{ needs.validate.outputs.prerelease }}
        run: |
          echo "## Hermes-Relay Android v${{ needs.validate.outputs.version }}" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          if [ "$PRERELEASE" != "true" ]; then
            echo "✅ **Published the exact signed Play-preflight artifacts**" >> "$GITHUB_STEP_SUMMARY"
          elif [ -n "$HERMES_KEYSTORE_BASE64" ]; then
            echo "✅ **Release-signed HR Candidate app** — separate package ID; never uploaded to Play" >> "$GITHUB_STEP_SUMMARY"
          else
            echo "⚠️ **Debug-signed HR Candidate app** — separate package ID; never uploaded to Play" >> "$GITHUB_STEP_SUMMARY"
          fi
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "### Artifacts" >> "$GITHUB_STEP_SUMMARY"
          echo '```' >> "$GITHUB_STEP_SUMMARY"
          find app/build/preflight-artifacts -maxdepth 1 -type f -exec ls -la {} + >> "$GITHUB_STEP_SUMMARY" 2>/dev/null || true
          find app/build/outputs/apk -name '*.apk' -exec ls -la {} + >> "$GITHUB_STEP_SUMMARY" 2>/dev/null || true
          find app/build/outputs/bundle -name '*.aab' -exec ls -la {} + >> "$GITHUB_STEP_SUMMARY" 2>/dev/null || true
          echo '```' >> "$GITHUB_STEP_SUMMARY"

  request-backmerge:
    name: Request stable release backmerge
    needs: [validate, release]
    if: needs.validate.outputs.prerelease != 'true'
    permissions:
      actions: write
      contents: read
    runs-on: ubuntu-latest
    steps:
      - name: Dispatch fail-closed release reconciliation
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: android-v${{ needs.validate.outputs.version }}
        run: |
          gh workflow run release-backmerge.yml \
            --repo "$GITHUB_REPOSITORY" \
            --ref main \
            -f release_tag="$RELEASE_TAG"