infrastructure-download-external.yml

name: "Composite: Sync 3rd party packages"
on:
  workflow_call:
    inputs:
      ENABLED:
        required: false
        type: boolean
        default: true
      ACCESS_NAME:
        required: false
        type: string
        default: ${{ github.repository_owner }}
      BUILD_BRANCH:
        required: false
        type: string
        default: 'main'
      BUILD_RUNNER:
        required: false
        type: string
        default: "ubuntu-latest"
      HOST_DEPLOY:
        required: false
        type: string
        default: "repo.armbian.com"
      HOST_USER:
        required: false
        type: string
        default: "upload"
      REFERENCE:
        required: false
        type: string
        default: "main"
      HIDE_NO_UPDATE:
        required: false
        type: boolean
        default: false
      PURGE:
        required: false
        type: boolean
        default: false
      SKIP_VERSION_CHECK:
        required: false
        type: boolean
        default: false
      CHUNK_INDEX:
        # Which slice of the matrix this invocation processes (0..CHUNK_COUNT-1).
        # Used to keep strategy.matrix under GitHub Actions' 256-entry cap when
        # the number of packages × arches × releases grows past that. Defaults
        # to 0/1 so the workflow still works when called un-chunked.
        required: false
        type: number
        default: 0
      CHUNK_COUNT:
        required: false
        type: number
        default: 1
    secrets:
      GPG_KEY1:
        required: true
      GPG_KEY2:
        required: true
      ACCESS_TOKEN:
        required: true
      KEY_UPLOAD:
        required: false
      HOST_UPLOAD:
        required: true
      HOST_UPLOAD_USER:
        required: true
      HOST_UPLOAD_PORT:
        required: true
      KNOWN_HOSTS_ARMBIAN_UPLOAD:
        required: true

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  PR_NUMBER: ${{ github.event.number }}
  PACKAGES_URL: "https://fi.mirror.armbian.de/apt"
  UPLOAD_PATH: "storage/incoming/external"

jobs:

  perm:
    name: "Restore permissions"
    runs-on: repository-sync
    if: ${{ inputs.ENABLED == true }}
    steps:
      - name: "Restore permissions"
        run: |

          sudo chown -R ${{ secrets.HOST_UPLOAD_USER }}:gha-runners /armbian/openssh-server/storage/{debs,debs-beta,artifacts}

  preclean:
    name: "Purge"
    needs: perm
    # Purge only in chunk 0. The preclean/postclean pair doesn't use
    # CHUNK_INDEX to filter its matrix — it builds the same
    # (release × package) list on every chunk and runs repo.sh -c delete
    # against /publishing/repository-debs. With 4 chunks that meant 4
    # parallel invocations of aptly's delete op racing on the same
    # repository state; aptly serialises via its own lockfile but the
    # fanout is still pure waste at best and a corruption hazard when a
    # held lock times out. Package download IS parallel-friendly (each
    # chunk fetches its own slice of debs into /incoming/debs/external),
    # but the repo-side purge is a single-threaded operation on shared
    # state. Gate it to chunk 0 so it runs exactly once per workflow.
    if: ${{ inputs.PURGE == true && inputs.CHUNK_INDEX == 0 }}
    runs-on: ubuntu-latest
    outputs:
      matrix:  ${{steps.json.outputs.JSON_CONTENT}}
    steps:
      - name: "Checkout Armbian build Framework"
        uses: actions/checkout@v6
        with:
          repository: armbian/build
          ref: ${{ inputs.REFERENCE || inputs.branch || 'main' }}
          clean: false
          fetch-depth: 1
          path: build

      - name: "Make JSON"
        id: json
        run: |

          pkg="code,codium,google-chrome-stable,anubis,armbian-config,box64,box64-android,gh,min,microsoft-edge-stable,zoom,armbian-firmware,armbian-firmware-full"
          echo 'JSON_CONTENT<<EOF' >> $GITHUB_OUTPUT
          releases=($(grep "supported\|csc" build/config/distributions/*/support | cut -d"/" -f4))
          for i in ${releases[@]}; do
              packages=($(echo "$pkg" | tr ',' '\n'))
                  for j in ${packages[@]}; do
                      echo "{\"release\":\"${i}\",\"package\":\"$j\"}"
                  done
              done | jq -s >> $GITHUB_OUTPUT
          echo 'EOF' >> $GITHUB_OUTPUT

  postclean:
    needs: preclean
    # Same chunk-0 gate as preclean (see its comment): this is the
    # repo.sh -c delete pass, which mutates shared aptly state and
    # MUST run single-threaded. The inner matrix already has
    # max-parallel: 1; the chunk gate here prevents 4 parallel
    # copies of that same serialised matrix from racing each other.
    if: ${{ inputs.PURGE == true && inputs.CHUNK_INDEX == 0 }}
    strategy:
      fail-fast: false
      max-parallel: 1
      matrix:
        include: ${{ fromJson(needs.preclean.outputs.matrix) }}

    name: "Purge old ${{ matrix.package }} from ${{ matrix.release }}"
    timeout-minutes: 60
    runs-on: repository
    steps:

      # Pre-chown before checkout. The Purge step below runs sudo
      # against /publishing/repository-debs and against the runner's
      # workspace-relative tools/repository/repo.sh output — both can
      # leave root-owned files under $GITHUB_WORKSPACE, so a later
      # non-root actions/checkout@v6 with clean: true (in the caller
      # workflow's Copying job) fails with EACCES. Reclaim ownership
      # first so the workspace is always deletable by the runner user.
      - name: Fix workspace ownership
        if: always()
        run: |
          sudo chown -R "$(id -u)":"$(id -g)" "$GITHUB_WORKSPACE" || true

      - name: Checkout build repository
        uses: actions/checkout@v6
        with:
          repository: armbian/build
          fetch-depth: 1
          clean: false

      - name: Purge packages
        run: |

          # take ownership
          sudo chown -R ${USER}:gha-runners /publishing/repository-debs

          PKG="${{ matrix.package }}"

          LIST=$(
            tools/repository/repo.sh -i /incoming/debs -o /publishing/repository-debs -r ${{ matrix.release }} \
              | sed 's/^[[:space:]]*//' \
              | grep "^${PKG}_" || true
          )

          COUNT=$(printf "%s\n" "$LIST" | grep -c . || true)

          if (( COUNT > 1 )); then
              # Display & log header
              echo "Found $COUNT packages for $PKG — deleting older versions" \
                | tee -a "$GITHUB_STEP_SUMMARY" >/dev/null

              # Determine newest version
              LATEST=$(printf "%s\n" "$LIST" | sort -V | tail -n 1)

              VERSION="${LATEST#${PKG}_}"   # strip pkg_
              VERSION="${VERSION%_*}"       # strip _ARCH

              echo "Newest version: $VERSION" \
                | tee -a "$GITHUB_STEP_SUMMARY" >/dev/null

              # Pretty print command in both outputs
              {
                echo '### 🧹 Delete package'
                echo '```bash'
                echo "tools/repository/repo.sh -o /publishing/repository-debs -r ${{ matrix.release }} -c delete -l 'Name (= $PKG), \$Version (<< $VERSION)'"
                echo '```'
              } | tee -a "$GITHUB_STEP_SUMMARY" >/dev/null

              # === RUN DELETE OPERATION ===
              tools/repository/repo.sh -i /incoming/debs -o /publishing/repository-debs -r ${{ matrix.release }} -c delete -l "Name (= $PKG), \$Version (<< $VERSION)"

          else
              echo "Only $COUNT package present — skipping delete" \
                | tee -a "$GITHUB_STEP_SUMMARY" >/dev/null
          fi

  start:
    runs-on: ${{ inputs.BUILD_RUNNER }}
    if: ${{ inputs.ENABLED == true }}
    needs: perm
    name: "Mirror"
    outputs:
      matrix: ${{steps.lists.outputs.matrix}}
      # 'true' when the matrix has real work; 'false' when start
      # only emitted the {name:none,...} placeholder (empty slice
      # for this chunk, or no actionable changes at all). The
      # download job gates on this via a job-level `if:` so an
      # empty chunk skips the entire matrix expansion instead of
      # trying to source os/external/none.conf.
      has_work: ${{steps.lists.outputs.has_work}}
    steps:

      - name: Fix workspace ownership
        if: always()
        run: |

          sudo chown -R "$(id -u)":"$(id -g)" "$GITHUB_WORKSPACE" || true

      - name: Install SSH key
        uses: shimataro/ssh-key-action@v2
        with:
          key: ${{ secrets.KEY_UPLOAD }}
          known_hosts: ${{ secrets.KNOWN_HOSTS_ARMBIAN_UPLOAD }}
          if_key_exists: replace

      - name: Create a temporary artifact folder
        run: |
          mkdir -p downloads
          cd downloads
          echo "${{ inputs.HOST_DEPLOY }}/" > url.txt
          echo "artifacts/${{ env.PR_NUMBER }}/" > path.txt

      - name: Upload Artifact
        uses: actions/upload-artifact@v7
        with:
          name: assets-for-download-${{ inputs.CHUNK_INDEX }}
          path: downloads
          overwrite: true
          retention-days: 5

      - name: Remove temporary repositories
        run: |
          # Note: StrictHostKeychecking=no is used here; consider using proper known_hosts in production
          ssh -o StrictHostKeychecking=no -p ${{ secrets.HOST_UPLOAD_PORT }} \
            ${{ inputs.HOST_USER }}@${{ inputs.HOST_DEPLOY }} \
            "rm -rf ${UPLOAD_PATH}/artifacts/*"

      - name: Checkout Armbian OS repository
        uses: actions/checkout@v6
        with:
          repository: armbian/os
          path: os
          fetch-depth: '2'
          clean: false

      - name: Get changed files
        id: changed-files
        uses: tj-actions/changed-files@v47
        with:
          path: os
          files: |
            external/*.conf

      - name: Build list
        id: lists
        run: |
          # Install jq if not available
          command -v jq >/dev/null 2>&1 || sudo apt-get install -y jq

          echo "::debug::Changed files: ${{ steps.changed-files.outputs.all_changed_files }}" >&2
          echo "::debug::REFERENCE input: ${{ inputs.REFERENCE }}" >&2

          # Build list of conf files
          if [[ "${{ inputs.REFERENCE }}" =~ ^(main|)$ ]]; then
            # Get all conf files
            MATRIX_LIST=()
            while IFS= read -r -d '' conf_file; do
              conf_name=$(basename "$conf_file" .conf)
              MATRIX_LIST+=("$conf_name")
            done < <(find os/external/*.conf -print0 | sort -z)
          else
            # Get only changed conf files
            MATRIX_LIST=()
            CHANGED="${{ steps.changed-files.outputs.all_changed_files }}"
            if [[ -n "$CHANGED" ]]; then
              while IFS= read -r conf_file; do
                conf_name=$(echo "$conf_file" | cut -d"." -f1 | cut -d"/" -f2)
                MATRIX_LIST+=("$conf_name")
              done < <(echo "$CHANGED" | tr " " "\n")
            fi
          fi

          echo "::debug::MATRIX content: ${MATRIX_LIST[*]}" >&2

          # Build detailed matrix - expand each arch and release combination
          echo "::notice::Building matrix..." >&2

          MATRIX_JSON=$(
          for conf_file in "${MATRIX_LIST[@]}"; do
            echo "::debug::Processing conf file: ${conf_file}" >&2
            [[ -f "os/external/${conf_file}.conf" ]] || continue

            # Source the conf file to get variables
            . "os/external/${conf_file}.conf"

            echo "::debug::${conf_file} - ARCH: ${ARCH}, RELEASE: ${RELEASE}, TARGET: ${TARGET}" >&2

            # Expand architectures (colon-separated)
            archs=($(echo "$ARCH" | tr ':' ' '))

            # Expand releases
            if [[ "${RELEASE}" == "all" ]]; then
              # Default releases for "all"
              releases=("bookworm" "trixie" "forky" "jammy" "noble" "resolute")
            elif [[ "${RELEASE}" == *":"* ]]; then
              # Colon-separated releases
              IFS=':' read -ra releases <<< "$RELEASE"
            else
              # Single release
              releases=("$RELEASE")
            fi

            # Generate matrix entry for each arch x release combination
            for arch in "${archs[@]}"; do
              for release in "${releases[@]}"; do
                # Determine if we need QEMU (non-amd64)
                needs_qemu="false"
                [[ "$arch" != "amd64" ]] && needs_qemu="true"

                echo "::debug::Generating entry: package=${conf_file}, arch=${arch}, release=${release}, needs_qemu=${needs_qemu}" >&2

                # Determine runner based on architecture and method
                # Force amd64 runner for aptly method due to stability issues on ARM
                if [[ "${METHOD:-aptly}" == "aptly" ]]; then
                  # Always use amd64 runner for aptly, use QEMU for other arches
                  runner='["docker", "X64"]'
                  image_arch="amd64"
                else
                  # Use architecture-specific runners for other methods (gh, direct)
                  case "${arch}" in
                    amd64)
                      runner='["docker", "X64"]'
                      image_arch="${arch}"
                      ;;
                    arm64)
                      runner='["docker", "ARM64"]'
                      image_arch="${arch}"
                      ;;
                    armhf|riscv64)
                      runner='["ubuntu-latest"]'
                      runner='["docker", "X64"]'
                      image_arch="amd64"  # Use amd64 image with QEMU emulation
                      ;;
                    *)
                      runner='["ubuntu-latest"]'
                      image_arch="amd64"
                      ;;
                  esac
                fi

                # Output JSON object for this combination - use pre-built Docker images
                jq -n \
                  --arg name "${conf_file}" \
                  --arg arch "${arch}" \
                  --arg release "${release}" \
                  --arg target "${TARGET:-main}" \
                  --arg method "${METHOD:-aptly}" \
                  --arg install "${INSTALL:-}" \
                  --arg runner "${runner}" \
                  --arg image_arch "${image_arch}" \
                  --arg registry "ghcr.io/${{ github.repository_owner }}" \
                  --argjson needs_qemu "${needs_qemu}" \
                  '{name: $name, arch: $arch, release: $release, target: $target, method: $method, install: $install, runner: ($runner | fromjson), image_arch: $image_arch, registry: $registry, needs_qemu: $needs_qemu}'
              done
            done
          done | jq -s '{"include": .}'
          )

          # Check if matrix is valid
          MATRIX_COUNT=$(echo "${MATRIX_JSON}" | jq '.include | length')

          # has_work tracks whether the resulting matrix has any real
          # entries vs the {name:none,...} placeholder. The download
          # job's job-level `if:` reads this output and skips the
          # whole matrix expansion when has_work='false', avoiding the
          # source of os/external/none.conf that would otherwise hard-
          # fail on the placeholder entry.
          HAS_WORK="true"

          # Handle empty matrix - add a dummy entry that will be skipped
          if [[ "${MATRIX_COUNT}" -eq 0 ]]; then
            echo "::warning::No matrix entries generated, adding placeholder" >&2
            MATRIX_JSON_COMPACTED='{"include":[{"name":"none","arch":"amd64","release":"bookworm"}]}'
            HAS_WORK="false"
          else
            # Chunk the matrix so each invocation keeps strategy.matrix
            # below GitHub Actions' 256-entry cap. Callers that don't
            # know about chunking get CHUNK_COUNT=1 and pass the whole
            # thing through (legacy behavior).
            #
            # Validate the inputs explicitly. workflow_call input
            # `type: number` is only enforced at the YAML boundary;
            # direct API / curl invocations or templated callers can
            # send anything that ends up as a string in the env. Bash's
            # arithmetic context silently treats non-numeric as 0,
            # which would let "abc" pass `-lt 1` and reset CHUNK_COUNT
            # to 1 with no warning. Regex-check first, then range.
            CHUNK_INDEX="${{ inputs.CHUNK_INDEX }}"
            CHUNK_COUNT="${{ inputs.CHUNK_COUNT }}"

            if [[ ! "${CHUNK_INDEX}" =~ ^[0-9]+$ ]]; then
              echo "::error::CHUNK_INDEX=${CHUNK_INDEX} is not a non-negative integer" >&2
              exit 1
            fi
            if [[ ! "${CHUNK_COUNT}" =~ ^[0-9]+$ ]]; then
              echo "::error::CHUNK_COUNT=${CHUNK_COUNT} is not a non-negative integer" >&2
              exit 1
            fi
            if [[ "${CHUNK_COUNT}" -lt 1 ]]; then
              echo "::error::CHUNK_COUNT=${CHUNK_COUNT} must be >= 1" >&2
              exit 1
            fi
            if [[ "${CHUNK_INDEX}" -ge "${CHUNK_COUNT}" ]]; then
              echo "::error::CHUNK_INDEX=${CHUNK_INDEX} must be < CHUNK_COUNT=${CHUNK_COUNT}" >&2
              exit 1
            fi

            # Slice jq: split includes into CHUNK_COUNT roughly-equal
            # groups by modular index (not contiguous ranges) so a
            # slow package type doesn't cluster into one chunk.
            SLICED=$(echo "${MATRIX_JSON}" | jq -c \
              --argjson idx "${CHUNK_INDEX}" \
              --argjson cnt "${CHUNK_COUNT}" \
              '{include: [.include | to_entries[] | select(.key % $cnt == $idx) | .value]}')

            SLICE_COUNT=$(echo "${SLICED}" | jq '.include | length')
            echo "::notice::chunk ${CHUNK_INDEX}/${CHUNK_COUNT}: ${SLICE_COUNT} of ${MATRIX_COUNT} entries" >&2

            # Empty slice still needs a placeholder so strategy.matrix
            # is a valid (non-empty) value — but we set HAS_WORK=false
            # so the download job's job-level `if:` skips it before
            # the matrix even expands.
            if [[ "${SLICE_COUNT}" -eq 0 ]]; then
              MATRIX_JSON_COMPACTED='{"include":[{"name":"none","arch":"amd64","release":"bookworm"}]}'
              HAS_WORK="false"
            else
              MATRIX_JSON_COMPACTED="${SLICED}"
            fi
            echo "::debug::Compacted matrix JSON: ${MATRIX_JSON_COMPACTED}" >&2
          fi

          echo "matrix=${MATRIX_JSON_COMPACTED}" >> $GITHUB_OUTPUT
          echo "has_work=${HAS_WORK}" >> $GITHUB_OUTPUT

  download:
    needs: [start]
    # Skip the whole job when start emitted a placeholder matrix
    # (no work for this chunk, or no actionable changes at all).
    # Job-level `if:` cannot reference `matrix.*` because matrix
    # is expanded after if-evaluation; using a needs.* output works
    # because those resolve at job-graph time.
    if: needs.start.outputs.has_work == 'true'
    outputs:
      project: ${{steps.make.outputs.project}}
    strategy:
      fail-fast: false
      max-parallel: 180
      matrix: ${{fromJson(needs.start.outputs.matrix)}}

    name: "${{ matrix.name }}:${{ matrix.release }}:${{ matrix.arch }}"
    runs-on: ${{ matrix.runner }}
    container:
      image: ${{ matrix.registry }}/repository-update:${{ matrix.release }}-${{ matrix.image_arch }}
      options: --user root
      credentials:
        username: ${{ github.actor }}
        password: ${{ secrets.GITHUB_TOKEN }}
    steps:

      - name: Install SSH key
        uses: shimataro/ssh-key-action@v2
        with:
          key: ${{ secrets.KEY_UPLOAD }}
          known_hosts: ${{ secrets.KNOWN_HOSTS_ARMBIAN_UPLOAD }}
          if_key_exists: replace

      - name: Import GPG key 1
        uses: crazy-max/ghaction-import-gpg@v7
        env:
          HOME: /root
          GNUPGHOME: /root/.gnupg
        with:
          gpg_private_key: ${{ secrets.GPG_KEY1 }}

      - name: Import GPG key 2
        uses: crazy-max/ghaction-import-gpg@v7
        with:
          gpg_private_key: ${{ secrets.GPG_KEY2 }}

      - name: Checkout Armbian OS scripts
        uses: actions/checkout@v6
        with:
          repository: armbian/os
          path: os
          ref: ${{ inputs.REFERENCE }}
          fetch-depth: '1'
          clean: false

      - name: Checkout Armbian build script
        uses: actions/checkout@v6
        with:
          repository: armbian/build
          path: build
          fetch-depth: '1'
          clean: false

      - name: Install GPG keys
        shell: bash
        run: |
          # Import all GPG keys from the repository
          find os/external/keys/ -type f -name "*.gpg" -exec gpg --import --no-default-keyring --keyring trustedkeys.gpg "{}" \;

          # Install appropriate keyring based on container type
          if grep -q "debian" /etc/os-release; then
            apt-get -y install debian-keyring 2>&1 | grep -v "^gpg:" || true
          elif grep -q "ubuntu" /etc/os-release; then
            apt-get -y install ubuntu-keyring 2>&1 | grep -v "^gpg:" || true
          fi

          # Import additional keys with timeout and suppress verbose output
          # Use timeout to prevent hanging on unavailable keyservers
          if timeout 30 gpg --no-default-keyring --keyring trustedkeys.gpg \
            --keyserver keyserver.ubuntu.com \
            --recv-keys 648ACFD622F3D138 0E98404D386FA1D9 2>&1 | grep -v "not changed\|unchanged\|not checked" || true; then
            echo "::notice::GPG keys imported successfully"
          else
            echo "::warning::Some GPG keys could not be imported from keyserver (non-critical)"
          fi

      - name: "Prepare machine"
        id: preparing
        shell: bash
        run: |

          # Load configuration
          . os/external/${{ matrix.name }}.conf

          echo "::debug::Config loaded - URL: ${URL}, KEY: ${KEY}, INSTALL: ${INSTALL}, ARCH: ${ARCH}, RELEASE: ${RELEASE}"

          APTLY_CONF="-max-tries=3 "
          [[ "${CHECKSUM}" == "ignore" ]] && APTLY_CONF+="-ignore-checksums "
          [[ "${SIGNATURES}" == "ignore" ]] && APTLY_CONF+="-ignore-signatures "

          # Read existing releases and create folder structure
          rm -rf build/output/{debs,debs-beta}
          ALL_RELEASES=($(grep -rw build/config/distributions/*/support -ve 'eos' | cut -d"/" -f4 ))
          for i in ${ALL_RELEASES[@]}; do
            mkdir -p build/output/{debs,debs-beta}/${i}
            mkdir -p build/output/{debs,debs-beta}/extra/${i}-utils
            mkdir -p build/output/{debs,debs-beta}/extra/${i}-desktop
            # Add example.deb to each subfolder to ensure empty repos are published
            for repo_root in build/output/debs build/output/debs-beta; do
              cp build/tools/repository/example.deb ${repo_root}/${i}/
              cp build/tools/repository/example.deb ${repo_root}/extra/${i}-utils/
              cp build/tools/repository/example.deb ${repo_root}/extra/${i}-desktop/
            done
          done

          needs_qemu='${{ matrix.needs_qemu }}'
          arch='${{ matrix.arch }}'
          release='${{ matrix.release }}'

          # Configure Ubuntu foreign architecture sources (only needed for aptly method)
          if [[ -r /etc/os-release ]]; then
            . /etc/os-release
            if [[ "${ID:-}" == "ubuntu" ]]; then
              # Only add foreign arch sources when needed
              if [[ "$needs_qemu" == "true" && "$arch" != "amd64" ]]; then
                # Enable foreign architecture
                dpkg --add-architecture "$arch"

                SRC="/etc/apt/sources.list.d/ubuntu-${arch}.sources"
                KEYRING="/usr/share/keyrings/ubuntu-archive-keyring.gpg"

                # Create source only if it does not exist
                if [[ ! -f "$SRC" ]]; then
                  printf '%s\n' \
                    "Types: deb" \
                    "URIs: http://ports.ubuntu.com/ubuntu-ports" \
                    "Suites: ${release} ${release}-updates ${release}-backports" \
                    "Components: main restricted universe multiverse" \
                    "Architectures: ${arch}" \
                    "Signed-By: ${KEYRING}" \
                    > "$SRC"
                fi
              fi
            fi
          fi

      - name: "Download method: ${{ matrix.method }}"
        id: calculate
        shell: bash
        run: |

          # Load configuration
          . os/external/${{ matrix.name }}.conf

          # `warn_skip` — bail out of this matrix slot on a broken
          # upstream (404, deleted release, dead mirror, …) without
          # failing the slot. Emits a ::warning:: annotation visible
          # on the run summary, appends a "skipped" row to the step
          # summary so the failure is tracked alongside successful
          # updates, then exits 0 so the matrix slot stays green and
          # the workflow's other slots keep running.
          #
          # Using `exit 0` (rather than `continue-on-error: true` at
          # the step level) because we also want the upload + repo
          # publishing logic AFTER this script to be skipped — we
          # have no .debs to push.
          warn_skip() {
            local reason="$*"
            echo "::warning::skipping ${{ matrix.name }} ${{ matrix.release }}/${{ matrix.arch }}: ${reason}" >&2
            {
              echo '| name | method | arch | release | needs_qemu | target | before | after | updating |'
              echo '|------|--------|------|---------|------------|--------|--------|-------|----------|'
              echo "| ${{ matrix.name }} | ${{ matrix.method }} | ${{ matrix.arch }} | ${{ matrix.release }} | ${{ matrix.needs_qemu }} | ${{ matrix.target }} | ${BEFORE_VERSION:-?} | — | ⚠️ skipped: ${reason} |"
            } >> "$GITHUB_STEP_SUMMARY"
            exit 0
          }

          SOURCE="temp/"
          rm -rf ${SOURCE}
          mkdir -p ${SOURCE}

          # Get current version from Armbian repository
          PKG="${INSTALL%% *}"

          # Determine the repository component based on TARGET
          if [[ "${TARGET}" == "main" ]]; then
            COMPONENT="main"
          else
            COMPONENT="extra/${{ matrix.release }}-${TARGET}"
          fi

          # Get version from main repository
          BEFORE_VERSION=""
          # Try main component, desktop component, then extra component
          for repo_component in "main" "${{ matrix.release }}-desktop" "${{ matrix.release }}-utils"; do
            # Build URL for Packages index
            CURRENT_PACKAGES_URL="${PACKAGES_URL}/dists/${{ matrix.release }}/${repo_component}/binary-${{ matrix.arch }}/Packages.gz"

            echo "::debug::Trying $CURRENT_PACKAGES_URL"

            # Download and parse the package index
            # Use || true to prevent SIGPIPE when wget fails (404)
            # shellcheck disable=SC2002
            BEFORE_VERSION="$(wget --timeout=10 --tries=3 -qO- "$CURRENT_PACKAGES_URL" 2>/dev/null | \
              gunzip 2>/dev/null | \
              awk -v pkg="$PKG" '
                /^Package: / { pkg_name = $2 }
                /^Version: / { if (pkg_name == pkg) { print $2; exit } }
              ')" || true

            if [[ -n "$BEFORE_VERSION" ]]; then
              echo "::notice::Found $PKG version $BEFORE_VERSION in ${repo_component}"
              break
            fi
          done

          if [[ -z "$BEFORE_VERSION" ]]; then
            echo "::warning::Could not find version for $PKG in repository, assuming new package"
            BEFORE_VERSION="0"
          fi

          echo "BEFORE_VERSION=${BEFORE_VERSION}" >> $GITHUB_OUTPUT

          # Download packages based on method
          if [[ ${METHOD} == gh ]]; then
            # GitHub release download method
            case "${{ matrix.arch }}" in
              amd64)
                PATTERNS+=('*amd64*.deb' '*x86_64*.deb' '*x64*.deb')
                ;;
              arm64)
                PATTERNS+=('*arm64*.deb' '*aarch64*.deb')
                ;;
              armhf)
                PATTERNS+=('*armhf*.deb' '*armv7*.deb' '*armv7l*.deb' '*armv6*.deb')
                ;;
              riscv64)
                PATTERNS+=('*riscv64*.deb')
                ;;
              *)
                echo "Unsupported arch: ${{ matrix.arch }}" >&2
                exit 1
                ;;
            esac

            # exception
            if [[ "${{ matrix.name }}" == "haos-supervised-installer" ]]; then
                PATTERNS=('*.deb')
            fi

            echo "Downloading from GitHub release ${TAG}"
            for p in "${PATTERNS[@]}"; do
              echo "  gh release download ${TAG} -p '$p' --repo ${URL}"
              gh release download "${TAG}" \
                -p "$p" \
                --repo "${URL}" \
                --dir "${SOURCE}" || true
            done

            # exception
            if [[ "${{ matrix.name }}" == "fastfetch" ]]; then
                rm -f "${SOURCE}"*polyfilled*
                rm -f "${SOURCE}"*armv6l.deb
            fi

            # Check if any .deb files were downloaded
            if ! ls "${SOURCE}"*.deb &> /dev/null; then
              warn_skip "no .deb matched for arch ${{ matrix.arch }} (release ${TAG}, repo ${URL}, patterns: ${PATTERNS[*]})"
            fi
          elif [[ ${METHOD} == direct ]]; then
            # Direct download method — wget the URL into the source dir.
            # `warn_skip` handles both transport failures (404, DNS,
            # connection reset) and the rare "200 OK, empty body" case.
            if ! wget -O "${SOURCE}${{ matrix.name }}.deb" "${URL}"; then
              warn_skip "wget '${URL}' failed (transport / 404 / dead mirror)"
            fi
            if ! ls "${SOURCE}"*.deb &> /dev/null; then
              warn_skip "${URL} produced no .deb"
            fi
          else
            # Aptly mirror method
            # Pin aptly state (critical in GH Actions containers)
            set -euo pipefail

            export HOME=/root
            APTLY_ROOT="/root/.aptly"
            APTLY_CFG="/root/.aptly.conf"
            mkdir -p "$APTLY_ROOT"
            printf '{ "rootDir": "%s" }\n' "$APTLY_ROOT" > "$APTLY_CFG"

            echo "::debug::APTLY_ROOT=$APTLY_ROOT"
            echo "::debug::APTLY_CFG=$APTLY_CFG"
            echo "::debug::Config file contents:"
            cat "$APTLY_CFG" >&2

            SOURCE="/root/.aptly/public/"

            # Configure filtering
            ADDITIONAL_FILTER=""
            FILTER_ARGS=()

            # Add -filter-with-deps only when filter does NOT include Name/Version
            if [[ "${GLOB:-}" != *Name* && "${GLOB:-}" != *Version* ]]; then
              ADDITIONAL_FILTER="-filter-with-deps"
            fi

            # Add filter only if GLOB is set/non-empty
            if [[ -n "${GLOB:-}" ]]; then
              FILTER_ARGS=(-filter="$GLOB")
            fi

            # Make mirror name unique per arch to avoid collisions
            MIRROR="${{ matrix.name }}-${{ matrix.release }}-${{ matrix.arch }}"

            echo "::debug::MIRROR_NAME=$MIRROR"
            echo "::debug::Original KEY='${KEY:-}'"

            # KEY may be:
            #   - "unstable contrib non-free"  (suite + components)
            #   - "bookworm"                  (suite only)
            #   - "./" / "public" / "stable"  (special/flat)
            read -r DIST REST <<<"${KEY:-}"
            COMPONENTS="$REST"

            echo "::debug::DIST='$DIST'"
            echo "::debug::REST='$REST'"
            echo "::debug::COMPONENTS='$COMPONENTS'"

            # Special/flat cases: do not pass components
            case "${KEY:-}" in
              "./"|"stable"|"public"|"stable non-free")
                DIST="$KEY"
                COMPONENTS=""
                ;;
            esac

            # If KEY did not include components, default to "main"
            if [[ -z "$COMPONENTS" && "$DIST" != "./" && "$DIST" != "stable" && "$DIST" != "public" && "$DIST" != "stable non-free" ]]; then
              COMPONENTS="main"
            fi

            echo "::debug::Final DIST='$DIST'"
            echo "::debug::Final COMPONENTS='$COMPONENTS'"

            # Prefer https (helps with EOF/proxy weirdness)
            URL="${URL:-}"
            URL="${URL/http:\/\//https:\/\/}"

            echo "::debug::URL='$URL'"
            echo "::debug::FILTER_ARGS='${FILTER_ARGS[*]}'"
            echo "::debug::ADDITIONAL_FILTER='$ADDITIONAL_FILTER'"
            echo "::debug::ARCH='${{ matrix.arch }}'"

            # Drop mirror if it already exists from previous run
            echo "::debug::Checking if mirror exists..."
            if aptly -config="$APTLY_CFG" mirror show "$MIRROR" &>/dev/null; then
              echo "::notice::Dropping existing mirror: $MIRROR"
              aptly -config="$APTLY_CFG" mirror drop "$MIRROR" || true
            else
              echo "::debug::Mirror does not exist yet"
            fi

            # Create mirror (distribution + optional components).
            # `|| warn_skip` catches a missing/dead Release file at
            # the URL — common cause of "broken source" — and skips
            # the slot instead of letting `set -euo pipefail` fail
            # the whole job.
            echo "::debug::Creating mirror..."
            if [[ -n "$COMPONENTS" ]]; then
              echo "::debug::aptly -config="$APTLY_CFG" -ignore-signatures ${FILTER_ARGS[*]} ${ADDITIONAL_FILTER} -architectures="${{ matrix.arch }}" mirror create "$MIRROR" "$URL" "$DIST" $COMPONENTS"
              # shellcheck disable=SC2086
              aptly -config="$APTLY_CFG" -ignore-signatures "${FILTER_ARGS[@]}" $ADDITIONAL_FILTER -architectures="${{ matrix.arch }}" mirror create "$MIRROR" "$URL" "$DIST" $COMPONENTS \
                || warn_skip "aptly mirror create failed (URL='$URL' DIST='$DIST' COMPONENTS='$COMPONENTS')"
            else
              echo "::debug::aptly -config="$APTLY_CFG" -ignore-signatures ${FILTER_ARGS[*]} ${ADDITIONAL_FILTER} -architectures="${{ matrix.arch }}" mirror create "$MIRROR" "$URL" "$DIST""
              # shellcheck disable=SC2086
              aptly -config="$APTLY_CFG" -ignore-signatures "${FILTER_ARGS[@]}" $ADDITIONAL_FILTER -architectures="${{ matrix.arch }}" mirror create "$MIRROR" "$URL" "$DIST" \
                || warn_skip "aptly mirror create failed (URL='$URL' DIST='$DIST')"
            fi
            echo "::debug::Mirror created successfully"

            # Update mirror with retry logic for EOF errors
            echo "::debug::Updating mirror..."
            MAX_RETRIES=3
            RETRY_COUNT=0
            UPDATE_SUCCESS=false

            while [[ $RETRY_COUNT -lt $MAX_RETRIES && "$UPDATE_SUCCESS" == "false" ]]; do
              if aptly -config="$APTLY_CFG" -max-tries=20 -ignore-signatures mirror update "$MIRROR"; then
                echo "::debug::Mirror updated successfully"
                UPDATE_SUCCESS=true
              else
                RETRY_COUNT=$((RETRY_COUNT + 1))
                if [[ $RETRY_COUNT -lt $MAX_RETRIES ]]; then
                  echo "::warning::Mirror update failed (attempt $RETRY_COUNT/$MAX_RETRIES), retrying..."
                  sleep 2
                  # Recreate mirror if it got corrupted
                  echo "::debug::Recreating mirror after failure..."
                  aptly -config="$APTLY_CFG" mirror drop "$MIRROR" || true
                  if [[ -n "$COMPONENTS" ]]; then
                    # shellcheck disable=SC2086
                    aptly -config="$APTLY_CFG" -ignore-signatures "${FILTER_ARGS[@]}" $ADDITIONAL_FILTER -architectures="${{ matrix.arch }}" mirror create "$MIRROR" "$URL" "$DIST" $COMPONENTS
                  else
                    # shellcheck disable=SC2086
                    aptly -config="$APTLY_CFG" -ignore-signatures "${FILTER_ARGS[@]}" $ADDITIONAL_FILTER -architectures="${{ matrix.arch }}" mirror create "$MIRROR" "$URL" "$DIST"
                  fi
                else
                  warn_skip "aptly mirror update failed after $MAX_RETRIES attempts (URL='$URL' DIST='$DIST')"
                fi
              fi
            done

            # Snapshot. Failure here is rare (local aptly state op,
            # not a remote fetch) but `set -e` would still kill the
            # job, so route through warn_skip for consistency.
            echo "::debug::Creating snapshot..."
            aptly -config="$APTLY_CFG" snapshot create "$MIRROR" from mirror "$MIRROR" \
              || warn_skip "aptly snapshot create failed (MIRROR='$MIRROR')"
            echo "::debug::Snapshot created successfully"

            # Publish.
            echo "::debug::Publishing snapshot..."
            aptly -config="$APTLY_CFG" publish -architectures="${{ matrix.arch }}" -batch=true snapshot "$MIRROR" \
              || warn_skip "aptly publish snapshot failed (MIRROR='$MIRROR')"
            echo "::debug::Snapshot published successfully"

            # Keep only latest version of each package

            ROOTS=($SOURCE)

            best_for_pkg_in_dir() {
              local dir="$1" pkg="$2"
              local best_ver="" best_file="" f ver

              while IFS= read -r -d '' f; do
                f="$(basename "$f")"
                ver="${f#${pkg}_}"; ver="${ver%%_*}"
                if [[ -z "$best_ver" ]] || dpkg --compare-versions "$ver" gt "$best_ver"; then
                  best_ver="$ver"
                  best_file="$f"
                fi
              done < <(find "$dir" -maxdepth 1 -type f -name "${pkg}_*.deb" -print0)

              [[ -n "$best_file" ]] && printf '%s\n' "$best_file"
            }

            for root in "${ROOTS[@]}"; do
              [[ -d "$root" ]] || continue

              # Process each directory that contains .deb files
              while IFS= read -r -d '' dir; do
                # List unique package names in this dir
                mapfile -t pkgs < <(find "$dir" -maxdepth 1 -type f -name '*.deb' -printf '%f\n' \
                  | sed -E 's/_.*//' | sort -u)

                ( cd "$dir"
                  for pkg in "${pkgs[@]}"; do
                    best="$(best_for_pkg_in_dir "$dir" "$pkg")"
                    [[ -n "$best" ]] || continue

                    # Delete all other versions of that package in this dir
                    while IFS= read -r -d '' f; do
                      b="$(basename "$f")"
                      [[ "$b" == "$best" ]] && continue
                      rm -f -- "$b"
                    done < <(find "$dir" -maxdepth 1 -type f -name "${pkg}_*.deb" -print0)

                    echo "[$dir] kept: $best"
                  done
                )
              done < <(find "$root" -type f -name '*.deb' -printf '%h\0' | sort -zu)
            done
          fi

          # Repack deb files with Armbian version
          if [[ "${{ matrix.name }}" == "firefox" ]]; then
            apt-get install -y devscripts
            DEBS=($(sudo find "${SOURCE}"* -type f -name '*firefox_*.deb'))
            for d in "${DEBS[@]}"; do
              BEFORE=$(deb-reversion -c ${d} -s armbian)
              # Add epoch 9
              AFTER=9:$(echo $BEFORE | cut -d":" -f2)
              echo "$d : $BEFORE -> $AFTER"
              DEBEMAIL=info@armbian.com deb-reversion -v $AFTER -s armbian $d
              rm $d
              mv *.deb ${SOURCE}
            done
          fi

          # Store info to GitHub Actions
          AFTER_VERSION=$(find "$SOURCE" -type f -name "${INSTALL%% *}*.deb" -exec dpkg-deb -f {} Version \; | sort | uniq | tail -n 1 | cut -d":" -f2)
          if [[ -z $AFTER_VERSION ]]; then
            AFTER_VERSION=$(find "$SOURCE" -type f -name "*.deb" -exec dpkg-deb -f {} Version \; | sort | uniq | tail -n 1 | cut -d":" -f2)
          fi
          PKG_LINES="$(find "$SOURCE" -type f -name "*.deb" -printf "%f\n" 2>/dev/null | sort | sed 's/$/<br>/')"
          echo "AFTER_VERSION=${AFTER_VERSION}" >> $GITHUB_OUTPUT

          # Determine if update is needed
          UPDATE_NEEDED="false"
          if dpkg --compare-versions "$AFTER_VERSION" gt "$BEFORE_VERSION"; then
            UPDATE_NEEDED="true"
          fi
          echo "UPDATE_NEEDED=${UPDATE_NEEDED}" >> $GITHUB_OUTPUT

          # Upload packages directly to remote storage to avoid race conditions
          # This prevents parallel jobs from overwriting each other's packages
          # Note: StrictHostKeychecking=no is used here; consider using proper known_hosts in production
          # Always upload to debs-beta for external packages
          if [[ ${TARGET} == main ]]; then
            # Upload to main repository directory
            find "$SOURCE" -type f -name "*.deb" -exec \
              rsync -e "ssh -o StrictHostKeychecking=no -p ${{ secrets.HOST_UPLOAD_PORT }}" \
              -arvc --mkpath --ignore-existing {} ${{ secrets.HOST_UPLOAD_USER }}@${{ secrets.HOST_UPLOAD }}:${UPLOAD_PATH}/debs-beta/ \;

            # Upload to debs only if version is newer than what's in repository
            # This is checked by comparing BEFORE_VERSION from the repository
            if dpkg --compare-versions "$AFTER_VERSION" gt "$BEFORE_VERSION"; then
              echo "::notice::Newer version $AFTER_VERSION found, uploading to debs"
              find "$SOURCE" -type f -name "*.deb" -exec \
                rsync -e "ssh -o StrictHostKeychecking=no -p ${{ secrets.HOST_UPLOAD_PORT }}" \
                -arvc --mkpath --ignore-existing {} ${{ secrets.HOST_UPLOAD_USER }}@${{ secrets.HOST_UPLOAD }}:${UPLOAD_PATH}/debs/ \;
            else
              echo "::notice::Version $AFTER_VERSION already exists in debs (has $BEFORE_VERSION), skipping upload"
            fi
          else
            # Upload to specific release directory in debs-beta
            find "$SOURCE" -type f -name "*.deb" -exec \
              rsync -e "ssh -o StrictHostKeychecking=no -p ${{ secrets.HOST_UPLOAD_PORT }}" \
              -arvc --mkpath --ignore-existing {} ${{ secrets.HOST_UPLOAD_USER }}@${{ secrets.HOST_UPLOAD }}:${UPLOAD_PATH}/debs-beta/extra/${{ matrix.release }}-${TARGET}/ \;

            # Upload to debs only if version is newer than what's in repository
            if dpkg --compare-versions "$AFTER_VERSION" gt "$BEFORE_VERSION"; then
              echo "::notice::Newer version $AFTER_VERSION found, uploading to debs/extra"
              find "$SOURCE" -type f -name "*.deb" -exec \
                rsync -e "ssh -o StrictHostKeychecking=no -p ${{ secrets.HOST_UPLOAD_PORT }}" \
                -arvc --mkpath --ignore-existing {} ${{ secrets.HOST_UPLOAD_USER }}@${{ secrets.HOST_UPLOAD }}:${UPLOAD_PATH}/debs/extra/${{ matrix.release }}-${TARGET}/ \;
            else
              echo "::notice::Version $AFTER_VERSION already exists in debs (has $BEFORE_VERSION), skipping upload"
            fi
          fi

          # Upload to repository if version changed
          if dpkg --compare-versions "$AFTER_VERSION" gt "$BEFORE_VERSION"; then
            # Generate summary table for updates
            echo '| name | method | arch | release | needs_qemu | target | before | after | updating |' >> $GITHUB_STEP_SUMMARY
            echo '|--------|-------|------|---------|------------|--------|--------|--------|----------|' >> $GITHUB_STEP_SUMMARY
            echo "| ${{ matrix.name }} | ${{ matrix.method }} | ${{ matrix.arch }} | ${{ matrix.release }} | ${{ matrix.needs_qemu }} | ${{ matrix.target }} | $BEFORE_VERSION | $AFTER_VERSION | ✅ |" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "packages: <br><code>$PKG_LINES</code>" >> $GITHUB_STEP_SUMMARY

          elif [[ "${{ inputs.HIDE_NO_UPDATE }}" == "true" ]]; then
            # Exit if HIDE_NO_UPDATE is enabled and no update needed
            echo "::notice::No update needed for ${{ matrix.name }} on ${{ matrix.arch }}, exiting early"
            exit 0
          fi

  clean:
    name: "Clean"
    needs: [download,postclean]
    if: ${{ always() }}
    runs-on: ${{ inputs.BUILD_RUNNER }}
    steps:

      - name: Clean artifacts
        uses: geekyeggo/delete-artifact@v6
        with:
          name: assets-for-download-${{ inputs.CHUNK_INDEX }}
          failOnError: false