LinuxInstall.yml

name: Linux_AppImage
run-name: Linux_AppImage (${{ inputs.source_sha }})

on:
  # Dispatch-only. PRs targeting `dev` run ci.yml; MSI/AppImage qualification
  # stays on the release-candidate path with an exact source SHA.
  workflow_dispatch:
    inputs:
      source_sha:
        description: "Accepted source commit; must match the selected workflow ref"
        required: true
        type: string

# Least privilege for GITHUB_TOKEN: checkout reads the repo and artifacts are
# uploaded via the job token.
permissions:
  contents: read

jobs:
  build_ubuntu:
    outputs:
      package_name: ${{ steps.get_version.outputs.package_name }}
    # The AppImage runtime is pinned for Ubuntu 22.04 compatibility.
    runs-on: ubuntu-22.04
    env:
      VCPKG_OVERLAY_PORTS: ${{ github.workspace }}/loop/vcpkg/overlays/linux:${{ github.workspace }}/loop/vcpkg/overlays/general
      VCPKG_INSTALLED_DIR: ${{ github.workspace }}/vcpkg_installed
      VCPKG_DEFAULT_BINARY_CACHE: ${{ github.workspace }}/vcpkg-binary-cache
      GNUPGHOME: ${{ github.workspace }}/gnupg
      QT_QPA_PLATFORM: offscreen

    steps:
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y autoconf autoconf-archive automake libtool libxcb-cursor0 libspeechd2 libfontconfig1-dev gnupg2 wget appstream libcups2 libcups2-dev xvfb xauth

      - name: Checkout repository
        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
        with:
          path: loop
          ref: ${{ github.sha }}
          fetch-depth: 0

      - name: Verify exact source SHA
        working-directory: loop
        env:
          EXPECTED_SOURCE_SHA: ${{ inputs.source_sha }}
          WORKFLOW_SOURCE_SHA: ${{ github.sha }}
        run: |
          if ! [[ "$EXPECTED_SOURCE_SHA" =~ ^[0-9a-fA-F]{40}$ ]]; then
            echo "::error::source_sha must be a full 40-character Git SHA"
            exit 1
          fi
          actual_sha="$(git rev-parse HEAD)"
          if [ "${actual_sha,,}" != "${WORKFLOW_SOURCE_SHA,,}" ]; then
            echo "::error::Checkout SHA $actual_sha does not match workflow source $WORKFLOW_SOURCE_SHA"
            exit 1
          fi
          if [ "${actual_sha,,}" != "${EXPECTED_SOURCE_SHA,,}" ]; then
            echo "::error::Checkout SHA $actual_sha does not match source_sha $EXPECTED_SOURCE_SHA"
            exit 1
          fi
          echo "LOOP_SOURCE_SHA=$actual_sha" >> "$GITHUB_ENV"
          echo "Packaging source SHA: $actual_sha"

      - name: Verify supply-chain pins
        working-directory: loop
        run: python3 scripts/ci/check_supply_chain_pins.py

      - name: Resolve verified packaging tool pins
        working-directory: loop
        run: |
          python3 - <<'PY'
          import json
          import os

          with open(".github/pins/packaging-tools.json", encoding="utf-8") as f:
              pins = json.load(f)

          values = {
              "APPIMAGETOOL_ASSET_ID": str(pins["appimagetool"]["assetId"]),
              "APPIMAGETOOL_SHA256": pins["appimagetool"]["sha256"],
              "RUNTIME_ASSET_ID": str(pins["appimageRuntime"]["assetId"]),
              "RUNTIME_SHA256": pins["appimageRuntime"]["sha256"],
          }

          with open(os.environ["GITHUB_ENV"], "a", encoding="utf-8") as f:
              for key, value in values.items():
                  f.write(f"{key}={value}\n")
          PY

      - name: Install appimagetool
        working-directory: loop
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          bash scripts/ci/download_verified.sh \
            --gh-asset "AppImage/appimagetool" \
            "$APPIMAGETOOL_ASSET_ID" \
            appimagetool-x86_64.AppImage \
            "$APPIMAGETOOL_SHA256"
          chmod +x appimagetool-x86_64.AppImage
          sudo mv appimagetool-x86_64.AppImage /usr/local/bin/appimagetool

      - name: Download verified AppImage runtime
        working-directory: loop
        env:
          GITHUB_TOKEN: ${{ github.token }}
        run: |
          # appimagetool otherwise resolves the *latest* type-2 runtime on its own.
          # Supply the exact pinned runtime so packaging never resolves a mutable
          # downstream binary.
          bash scripts/ci/download_verified.sh \
            --gh-asset "AppImage/type2-runtime" \
            "$RUNTIME_ASSET_ID" \
            "$GITHUB_WORKSPACE/runtime-x86_64" \
            "$RUNTIME_SHA256"
          chmod +x "$GITHUB_WORKSPACE/runtime-x86_64"

      - name: 'VCPKG: Set up VCPKG'
        run: |
          mkdir -p "$VCPKG_DEFAULT_BINARY_CACHE"
          VCPKG_COMMIT="$(python3 - <<'PY'
          import json
          with open("loop/vcpkg-configuration.json", encoding="utf-8") as f:
              print(json.load(f)["default-registry"]["baseline"])
          PY
          )"

          if ! [[ "$VCPKG_COMMIT" =~ ^[0-9a-f]{40}$ ]]; then
              echo "::error::Invalid vcpkg baseline: $VCPKG_COMMIT"
              exit 1
          fi

          git clone https://github.com/microsoft/vcpkg.git
          git -C vcpkg checkout --detach "$VCPKG_COMMIT"

          ACTUAL="$(git -C vcpkg rev-parse HEAD)"
          test "$ACTUAL" = "$VCPKG_COMMIT" || {
              echo "::error::vcpkg checkout does not match manifest baseline"
              exit 1
          }

          ./vcpkg/bootstrap-vcpkg.sh
          ./vcpkg/vcpkg integrate install
          echo "VCPKG_BINARY_SOURCES=clear;files,$VCPKG_DEFAULT_BINARY_CACHE,readwrite" >> "$GITHUB_ENV"

      - name: 'VCPKG: Cache vcpkg dependencies'
        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830  # v4
        with:
          path: |
            ./vcpkg/downloads
            ./vcpkg/packages
            ./vcpkg_installed
            ./vcpkg-binary-cache
          key: ${{ runner.os }}-vcpkg-v2-${{ hashFiles('**/vcpkg.json', '**/vcpkg-configuration.json') }}
          restore-keys: |
            ${{ runner.os }}-vcpkg-v2-

      - name: 'VCPKG: Install Project Dependencies'
        run: |
          # Seed the two GNU archives through the primary GNU host.  The
          # vcpkg portfiles prefer ftpmirror.gnu.org, which intermittently
          # returned 502/503 during package qualification; a verified
          # filename in downloads lets vcpkg reuse the archive and keeps the
          # existing portfile hash verification authoritative.
          mkdir -p downloads
          curl --fail --location --retry 5 --retry-delay 5 --retry-all-errors \
            --output downloads/automake-1.17.tar.gz \
            https://ftp.gnu.org/gnu/automake/automake-1.17.tar.gz
          curl --fail --location --retry 5 --retry-delay 5 --retry-all-errors \
            --output downloads/gperf-3.3.tar.gz \
            https://ftp.gnu.org/gnu/gperf/gperf-3.3.tar.gz
          ./vcpkg install --triplet x64-linux-release --x-manifest-root=${{ github.workspace }}/loop --x-install-root=$VCPKG_INSTALLED_DIR --clean-buildtrees-after-build --clean-packages-after-build
        working-directory: vcpkg

      - name: Install Qt
        uses: jurplel/install-qt-action@48d3ad6db93f3627c8ee7a0454bc6f3744f7e730  # v4.3.1
        with:
          version: '6.11.1'
          host: 'linux'
          target: 'desktop'
          dir: '${{ github.workspace }}/qt/'
          install-deps: 'true'
          modules: 'qtspeech qtmultimedia'
          cache: 'true'
          cache-key-prefix: ${{ runner.os }}-qt-6111

      - name: Build Project
        working-directory: loop
        run: |
          cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=../vcpkg/scripts/buildsystems/vcpkg.cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_VCPKG_BUILD_TYPE=Release -DLOOP_INSTALL_QT_DEPENDENCIES=ON -DLOOP_INSTALL_TO_USR=ON -DLOOP_LOOP_DISTRIBUTION=ON -DLOOP_PLUGIN_OCR=OFF -DLOOP_BUILD_PRODUCT_QUICK_A11Y_SMOKE=ON
          cmake --build build --target LoopEditor PdfTool ProductQuickAccessibilitySmoke release_translations -j6
          cmake --install build
          # Scan the whole install tree: on Linux the product libraries land in
          # usr/lib, not usr/bin (LOOP_INSTALL_LIB_DIR).  Only Windows collapses
          # both onto usr/bin.
          pwsh ./scripts/verify-loop-surface.ps1 -InstallDir "$GITHUB_WORKSPACE/loop/build/install" -Profile loop-release -BuildDir build -InstallManifestPath build/install_manifest.txt
          python3 scripts/verify-widgets-free-release-profile.py --install-dir build/install

      - name: Run product Quick accessibility qualification harness (native)
        working-directory: loop
        run: |
          # Qualify the INSTALLED tree (the tree a user runs and the tree the
          # Widgets-free profile is verified against), not the developer build
          # tree: the harness runs from a staging copy of build/install so the
          # LoopLibCore/LoopLibQuick and deployed Qt closure resolve from the
          # installed layout. Native is distinct from software and fatal on failure.
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          mkdir -p "$evidence_dir"
          set -o pipefail
          echo "source_sha=$LOOP_SOURCE_SHA" | tee "$evidence_dir/quick-a11y-native.txt"
          xvfb-run -a pwsh ./scripts/run-product-quick-a11y-smoke.ps1 -BuildDir build -InstallTree build/install -Backend native -Platform xcb -SourceSha "$LOOP_SOURCE_SHA" -EvidenceJson "$evidence_dir/quick-a11y-native.json" 2>&1 | tee -a "$evidence_dir/quick-a11y-native.txt"

      - name: Run product Quick accessibility qualification harness (software)
        working-directory: loop
        run: |
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          mkdir -p "$evidence_dir"
          set -o pipefail
          echo "source_sha=$LOOP_SOURCE_SHA" | tee "$evidence_dir/quick-a11y-software.txt"
          pwsh ./scripts/run-product-quick-a11y-smoke.ps1 -BuildDir build -InstallTree build/install -Backend software -SourceSha "$LOOP_SOURCE_SHA" -EvidenceJson "$evidence_dir/quick-a11y-software.json" 2>&1 | tee -a "$evidence_dir/quick-a11y-software.txt"

      - name: Verify installed-tree accessibility qualification evidence
        working-directory: loop
        run: |
          # Fail closed: a missing, skipped or failed native lane, or a software-only
          # record offered as the native claim, fails here even though each harness
          # run already exited zero.
          #
          # The native OS accessibility backend (AT-SPI) is not exercised here: the
          # hosted Linux runner is headless and has no accessibility bus, so the
          # native-accessibility lane is unavailable, not passing. Record it so it
          # cannot read as absent-and-fine; Windows drives the equivalent lane
          # (UI Automation) and requires it.
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          printf 'lane=native-accessibility-backend\nstatus=unavailable\nreason=headless Linux runner has no AT-SPI accessibility bus\nsource_sha=%s\n' "$LOOP_SOURCE_SHA" > "$evidence_dir/quick-a11y-native-accessibility-unavailable.txt"
          python3 scripts/ci/verify_quick_accessibility_evidence.py \
            --native "$evidence_dir/quick-a11y-native.json" \
            --software "$evidence_dir/quick-a11y-software.json" \
            --source-sha "$LOOP_SOURCE_SHA" \
            --install-tree build/install

      - name: Read version
        id: get_version
        run: |
          version=$(cat "loop/build/version.txt")
          echo "Version: $version"
          echo "appimagefilename=Loop-pdf-$version-x86_64.AppImage" >> $GITHUB_ENV
          echo "appimage_update_info=gh-releases-zsync|mberrys|Loop-pdf|latest|Loop-pdf-*-x86_64.AppImage.zsync" >> $GITHUB_ENV
          echo "AppImage file name: Loop-pdf-$version-x86_64.AppImage"
          echo "package_name=Loop-pdf-$version-x86_64.AppImage" >> "$GITHUB_OUTPUT"

      - name: Prepare AppDir for appimagetool
        working-directory: loop
        run: bash ./scripts/prepare-appdir.sh build/install

      - name: Prepare GPG home
        if: vars.SIGN_APPIMAGE == 'true'
        run: |
          rm -rf "$GNUPGHOME"
          install -d -m 700 "$GNUPGHOME"
          echo "use-agent" >> "$GNUPGHOME/gpg.conf"
          echo "pinentry-mode loopback" >> "$GNUPGHOME/gpg.conf"
          echo "allow-loopback-pinentry" >> "$GNUPGHOME/gpg-agent.conf"
          echo "allow-preset-passphrase" >> "$GNUPGHOME/gpg-agent.conf"
          gpgconf --kill gpg-agent
          echo "${{ secrets.PGP_PRIVATE_KEY }}" | gpg --batch --import
          for keygrip in $(gpg --list-secret-keys --with-keygrip "${{ secrets.PGP_KEY_ID }}" | grep Keygrip | awk '{print $3}'); do
            echo "${{ secrets.PGP_PASSPHRASE }}" | "$(gpgconf --list-dirs libexecdir)/gpg-preset-passphrase" --preset "$keygrip"
          done
        env:
          GNUPGHOME: ${{ env.GNUPGHOME }}

      - name: Pack AppImage (unsigned — V1 default)
        if: vars.SIGN_APPIMAGE != 'true'
        working-directory: loop/build
        run: |
          appimagetool \
            --runtime-file "$GITHUB_WORKSPACE/runtime-x86_64" \
            -u "${{ env.appimage_update_info }}" \
            install/ ${{ env.appimagefilename }}

      - name: Sign and Repack AppImage
        if: vars.SIGN_APPIMAGE == 'true'
        working-directory: loop/build
        run: |
          appimagetool \
            --runtime-file "$GITHUB_WORKSPACE/runtime-x86_64" \
            -u "${{ env.appimage_update_info }}" \
            -s --sign-key "${{ secrets.PGP_KEY_ID }}" \
            install/ ${{ env.appimagefilename }}
        env:
          GNUPGHOME: ${{ env.GNUPGHOME }}

      - name: Manual signature
        if: vars.SIGN_APPIMAGE == 'true'
        run: |
          gpg --batch --yes --verbose --pinentry-mode loopback --detach-sign --passphrase "${{ secrets.PGP_PASSPHRASE }}" --local-user "${{ secrets.PGP_KEY_ID }}" --output loop/build/${{ env.appimagefilename }}.sig loop/build/${{ env.appimagefilename }}
        env:
          GNUPGHOME: ${{ env.GNUPGHOME }}

      - name: Verify AppImage Detached Signature
        if: vars.SIGN_APPIMAGE == 'true'
        run: |
          echo "${{ secrets.PGP_PUBLIC_KEY }}" | gpg --batch --import
          gpg --verify loop/build/${{ env.appimagefilename }}.sig loop/build/${{ env.appimagefilename }}
        env:
          GNUPGHOME: ${{ env.GNUPGHOME }}

      - name: Run AppImage smoke test
        working-directory: loop
        env:
          QT_QPA_PLATFORM: offscreen
        run: |
          chmod +x "build/${{ env.appimagefilename }}"
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          mkdir -p "$evidence_dir"
          set -o pipefail
          bash ./scripts/smoke-test-appimage.sh "build/${{ env.appimagefilename }}" "loop-preflight/testdata/fixtures/bleed-adequate.pdf" 2>&1 | tee "$evidence_dir/appimage-smoke.txt"

      - name: Inspect AppImage package boundary
        working-directory: loop
        run: |
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          mkdir -p "$evidence_dir"
          set -o pipefail
          python3 scripts/ci/inspect_package_dependencies.py \
            --platform linux \
            --package "build/${{ env.appimagefilename }}" \
            --source-sha "$LOOP_SOURCE_SHA" \
            --expected-architecture x86-64 \
            --work-dir "$RUNNER_TEMP/loop-package-boundary-linux-work" \
            --output "$evidence_dir/evidence.json" \
            --report "$evidence_dir/inspection.txt" 2>&1 | tee "$evidence_dir/inspector.txt"

      - name: Generate final-artifact SBOM and notices
        working-directory: loop
        run: |
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          python3 scripts/ci/generate_package_sbom.py \
            --evidence "$evidence_dir/evidence.json" \
            --output "$evidence_dir/components.spdx.json"
          python3 scripts/ci/generate_package_third_party_notices.py \
            --evidence "$evidence_dir/evidence.json" \
            --output "$evidence_dir/THIRD_PARTY_NOTICES.txt"

      - name: Run Qt LGPL relink test
        working-directory: loop
        env:
          QT_QPA_PLATFORM: offscreen
        run: |
          evidence_dir="$RUNNER_TEMP/loop-package-boundary-linux"
          bash scripts/ci/run_qt_relink_test.sh \
            "build/${{ env.appimagefilename }}" \
            --output "$evidence_dir/qt-relink.txt"

      - name: Upload Linux package boundary evidence
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
        with:
          name: loop-package-boundary-linux-evidence
          path: ${{ runner.temp }}/loop-package-boundary-linux
          if-no-files-found: error
          retention-days: 30
          compression-level: 0

      - name: Upload AppImage Package
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
        with:
          name: ${{ env.appimagefilename }}
          path: ./loop/build/${{ env.appimagefilename }}
          retention-days: 30
          compression-level: 0

      - name: Prepare exact-source accessibility kit
        working-directory: loop
        run: python3 scripts/ci/quick_a11y_kit.py --binary build/usr/bin/ProductQuickAccessibilitySmoke --source-sha "$LOOP_SOURCE_SHA" --output "$RUNNER_TEMP/quick-a11y-kit"

      - name: Upload accessibility kit
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
        with:
          name: quick-a11y-kit-linux
          path: ${{ runner.temp }}/quick-a11y-kit
          if-no-files-found: error

      - name: Upload AppImage Signature File
        if: vars.SIGN_APPIMAGE == 'true'
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
        with:
          name: ${{ env.appimagefilename }}.sig
          path: ./loop/build/${{ env.appimagefilename }}.sig
          retention-days: 30
          if-no-files-found: warn
          compression-level: 0

      - name: Upload AppImage zsync File
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
        with:
          name: ${{ env.appimagefilename }}.zsync
          path: ./loop/build/${{ env.appimagefilename }}.zsync
          retention-days: 30
          if-no-files-found: warn
          compression-level: 0

      - name: Cleanup GPG home
        if: always() && vars.SIGN_APPIMAGE == 'true'
        run: |
          rm -rf "$GNUPGHOME"
        env:
          GNUPGHOME: ${{ env.GNUPGHOME }}

  qualify_linux:
    needs: build_ubuntu
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
        with:
          ref: ${{ github.sha }}
      - name: Install OS accessibility client
        run: |
          sudo apt-get update
          sudo apt-get install -y python3-gi gir1.2-atspi-2.0 at-spi2-core dbus-x11 xvfb xauth openbox x11-utils libxcb-cursor0 libspeechd2 libcups2
      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
        with:
          name: ${{ needs.build_ubuntu.outputs.package_name }}
          path: package
      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
        with:
          name: quick-a11y-kit-linux
          path: kit
      - name: Qualify final AppImage on a fresh runner
        env:
          LOOP_SOURCE_SHA: ${{ inputs.source_sha }}
          LOOP_PACKAGE_NAME: ${{ needs.build_ubuntu.outputs.package_name }}
        run: |
          set -euo pipefail
          test "$(git rev-parse HEAD)" = "$LOOP_SOURCE_SHA"
          python3 scripts/ci/quick_a11y_kit.py --source-sha "$LOOP_SOURCE_SHA" --output kit
          chmod +x "package/$LOOP_PACKAGE_NAME" kit/ProductQuickAccessibilitySmoke
          mkdir -p "$RUNNER_TEMP/native-qualification"
          python3 scripts/ci/inspect_package_dependencies.py --platform linux --package "package/$LOOP_PACKAGE_NAME" --source-sha "$LOOP_SOURCE_SHA" --work-dir "$RUNNER_TEMP/package-inspection" --output "$RUNNER_TEMP/native-qualification/package-boundary.json"
          export LOOP_INSTALL_TREE="$RUNNER_TEMP/package-inspection/appimage/squashfs-root"
          export LOOP_PACKAGE="$GITHUB_WORKSPACE/package/$LOOP_PACKAGE_NAME"
          unset QT_PLUGIN_PATH QML2_IMPORT_PATH QML_IMPORT_PATH LD_LIBRARY_PATH QT_ROOT_DIR LOOP_QT_ROOT
          dbus-run-session -- xvfb-run -a bash scripts/qualification/qualify-linux-accessibility.sh "$LOOP_INSTALL_TREE" "$GITHUB_WORKSPACE/kit" "$LOOP_PACKAGE" "$LOOP_SOURCE_SHA" "$RUNNER_TEMP/native-qualification" 2>&1 | tee "$RUNNER_TEMP/native-qualification/transcript.txt"
      - name: Upload clean-machine accessibility evidence
        if: always()
        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
        with:
          name: loop-native-accessibility-linux-evidence
          path: ${{ runner.temp }}/native-qualification
          if-no-files-found: error