iris_x_hermes/CI-SETUP.md

CI / Release setup — manual edit list

Everything needed for the Gitea workflows (CI + manual release). Items marked DONE were already applied; the rest are copy-paste instructions.

---

1. DONE — no action needed

• tests/test_android.py — vendored byte-identical mirror of hermes-agent/tests/gateway/test_android.py (the git-ignored hermes checkout is the canonical copy; keep the two in sync when you change that test).
• .pi-lens.json — added "ignore": ["tests/test_android.py"] so the scanner doesn't flag the vendored mirror.

---

2. NEW FILE: .gitea/workflows/ci.yml

Runs on every push to master and on PRs: gateway plugin tests + Kotlin host tests (android + desktop).

name: CI

on:
  push:
    branches: [master]
  pull_request:

jobs:
  gateway:
    name: Gateway plugin tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      # The gateway tests run inside the hermes-agent test harness, which is
      # git-ignored in this repo (read-only research reference). CI clones the
      # upstream repo at a pinned commit and drops in the vendored test copy.
      # Bump the pinned SHA when you update the local hermes-agent checkout.
      - name: Clone hermes-agent (pinned)
        run: |
          git clone https://github.com/NousResearch/hermes-agent.git hermes-agent
          git -C hermes-agent fetch --depth 1 origin 31f62d76af068abde3c699f91190e8ded07fd05b
          git -C hermes-agent checkout 31f62d76af068abde3c699f91190e8ded07fd05b

      - name: Sync venv
        run: |
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          cd hermes-agent
          uv sync

      - name: Run android gateway tests
        run: |
          cp tests/test_android.py hermes-agent/tests/gateway/test_android.py
          cd hermes-agent
          IRIS_PLUGIN_DIR="$GITHUB_WORKSPACE/gateway-plugin" \
            scripts/run_tests.sh tests/gateway/test_android.py

  kotlin:
    name: Kotlin tests (android host + desktop)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "21"

      # gradle.properties pins org.gradle.java.home to a local JDK path;
      # strip it so CI uses the JDK installed by setup-java.
      - name: Strip local JDK pin
        run: sed -i '/^org\.gradle\.java\.home/d' app/gradle.properties

      - name: Install Android SDK
        run: |
          export ANDROID_HOME="$HOME/android-sdk"
          mkdir -p "$ANDROID_HOME/cmdline-tools"
          curl -fsSL -o /tmp/ct.zip \
            https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
          unzip -q /tmp/ct.zip -d "$ANDROID_HOME/cmdline-tools"
          mv "$ANDROID_HOME/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest"
          yes | "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --licenses > /dev/null
          echo "ANDROID_HOME=$ANDROID_HOME" >> "$GITHUB_ENV"
          echo "sdk.dir=$ANDROID_HOME" > app/local.properties

      # Host-side tests only (no device needed). AGP auto-downloads the
      # missing SDK platforms (licenses accepted above).
      - name: Run host tests
        working-directory: app
        run: ./gradlew :shared:testAndroidHostTest :shared:desktopTest

---

3. NEW FILE: .gitea/workflows/release.yml

The release version is the repo-root VERSION file (single source of truth — "everything from here on out is vX.Y.Z" = bump VERSION and commit). Manual trigger: repo → Actions → Release → Run workflow, optionally with a changelog. It runs the same tests as CI, builds a signed Android APK + AAB and the Linux desktop packages (jpackage, JRE bundled), then creates the Gitea release v<VERSION> with all artifacts as download attachments.

Note: builds + release creation happen in ONE job because Gitea/act_runner does not implement the GitHub artifacts API (upload-artifact@v4+ fails with GHESNotSupportedError).

name: Release

on:
  workflow_dispatch:
    inputs:
      # The release version comes from the repo-root VERSION file (the single
      # source of truth) — bump it in a commit, then dispatch this workflow.
      changelog:
        description: "Release notes (markdown, shown on the release page). Single-line field — use literal \\n for line breaks."
        required: false
        type: string

jobs:
  gateway:
    name: Gateway plugin tests
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install uv
        run: curl -LsSf https://astral.sh/uv/install.sh | sh

      - name: Clone hermes-agent (pinned)
        run: |
          git clone https://github.com/NousResearch/hermes-agent.git hermes-agent
          git -C hermes-agent fetch --depth 1 origin 31f62d76af068abde3c699f91190e8ded07fd05b
          git -C hermes-agent checkout 31f62d76af068abde3c699f91190e8ded07fd05b

      - name: Sync venv
        run: |
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          cd hermes-agent
          # pytest lives in the `dev` extra — a plain `uv sync` leaves the
          # venv without it and run_tests.sh refuses to run.
          uv sync --extra dev

      - name: Run android gateway tests
        run: |
          cp tests/test_android.py hermes-agent/tests/gateway/test_android.py
          cd hermes-agent
          IRIS_PLUGIN_DIR="$GITHUB_WORKSPACE/gateway-plugin" \
            scripts/run_tests.sh tests/gateway/test_android.py

  kotlin:
    name: Kotlin tests (android host + desktop)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "21"

      - name: Strip local JDK pin
        run: sed -i '/^org\.gradle\.java\.home/d' app/gradle.properties

      - name: Install Android SDK
        run: |
          export ANDROID_HOME="$HOME/android-sdk"
          mkdir -p "$ANDROID_HOME/cmdline-tools"
          curl -fsSL -o /tmp/ct.zip \
            https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
          unzip -q /tmp/ct.zip -d "$ANDROID_HOME/cmdline-tools"
          mv "$ANDROID_HOME/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest"
          # Finite input from a file: `yes | sdkmanager` dies with SIGPIPE
          # (exit 141) under Gitea's `bash -e -o pipefail` once sdkmanager
          # exits before `yes` is done writing.
          for i in $(seq 100); do echo y; done > /tmp/sdk_licenses_yes.txt
          "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --licenses < /tmp/sdk_licenses_yes.txt > /dev/null
          echo "ANDROID_HOME=$ANDROID_HOME" >> "$GITHUB_ENV"
          echo "sdk.dir=$ANDROID_HOME" > app/local.properties

      - name: Run host tests
        working-directory: app
        run: ./gradlew :shared:testAndroidHostTest :shared:desktopTest

  # Gitea/act_runner does not implement the GitHub artifacts API
  # (upload-artifact@v4+ fails with GHESNotSupportedError), so the builds and
  # the release creation happen in ONE job — no artifact handoff between jobs.
  release:
    name: Build + create Gitea release
    runs-on: ubuntu-latest
    needs: [gateway, kotlin]
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-java@v4
        with:
          distribution: temurin
          java-version: "21"

      - name: Strip local JDK pin
        run: sed -i '/^org\.gradle\.java\.home/d' app/gradle.properties

      - name: Install Android SDK
        run: |
          export ANDROID_HOME="$HOME/android-sdk"
          mkdir -p "$ANDROID_HOME/cmdline-tools"
          curl -fsSL -o /tmp/ct.zip \
            https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
          unzip -q /tmp/ct.zip -d "$ANDROID_HOME/cmdline-tools"
          mv "$ANDROID_HOME/cmdline-tools/cmdline-tools" "$ANDROID_HOME/cmdline-tools/latest"
          # Finite input from a file: `yes | sdkmanager` dies with SIGPIPE
          # (exit 141) under Gitea's `bash -e -o pipefail` once sdkmanager
          # exits before `yes` is done writing.
          for i in $(seq 100); do echo y; done > /tmp/sdk_licenses_yes.txt
          "$ANDROID_HOME/cmdline-tools/latest/bin/sdkmanager" --licenses < /tmp/sdk_licenses_yes.txt > /dev/null
          echo "ANDROID_HOME=$ANDROID_HOME" >> "$GITHUB_ENV"
          echo "sdk.dir=$ANDROID_HOME" > app/local.properties

      # jpackage --type deb shells out to fakeroot, which the runner image
      # does not ship.
      - name: Install fakeroot (for jpackage --type deb)
        run: sudo apt-get update -qq && sudo apt-get install -y -qq fakeroot

      - name: Restore release keystore (from Gitea secrets)
        env:
          KS_B64: ${{ secrets.ANDROID_KEYSTORE_BASE64 }}
        run: |
          if [ -n "$KS_B64" ]; then
            echo "$KS_B64" | base64 -d > app/release.keystore
            echo "ANDROID_KEYSTORE_FILE=$GITHUB_WORKSPACE/app/release.keystore" >> "$GITHUB_ENV"
            echo "ANDROID_KEYSTORE_PASSWORD=${{ secrets.ANDROID_KEYSTORE_PASSWORD }}" >> "$GITHUB_ENV"
            echo "ANDROID_KEY_ALIAS=${{ secrets.ANDROID_KEY_ALIAS }}" >> "$GITHUB_ENV"
            echo "ANDROID_KEY_PASSWORD=${{ secrets.ANDROID_KEY_PASSWORD }}" >> "$GITHUB_ENV"
            echo "Building SIGNED release APK"
          else
            echo "::warning::ANDROID_KEYSTORE_BASE64 secret not set — falling back to a DEBUG apk (see CI-SETUP.md §5)"
          fi

      - name: Build APK + AAB
        run: |
          VERSION=$(cat "$GITHUB_WORKSPACE/VERSION")
          [ -n "$VERSION" ] || { echo "::error::VERSION file is missing or empty"; exit 1; }
          cd app
          if [ -n "$ANDROID_KEYSTORE_FILE" ]; then
            # APK for direct sideloading, AAB for Play Store uploads.
            ./gradlew :androidApp:assembleRelease :androidApp:bundleRelease -PappVersion="$VERSION"
            cp androidApp/build/outputs/apk/release/androidApp-release.apk \
              "$GITHUB_WORKSPACE/iris-android-v$VERSION.apk"
            cp androidApp/build/outputs/bundle/release/androidApp-release.aab \
              "$GITHUB_WORKSPACE/iris-android-v$VERSION.aab"
          else
            ./gradlew :androidApp:assembleDebug :androidApp:bundleDebug -PappVersion="$VERSION"
            cp androidApp/build/outputs/apk/debug/androidApp-debug.apk \
              "$GITHUB_WORKSPACE/iris-android-v$VERSION-debug.apk"
            cp androidApp/build/outputs/bundle/debug/androidApp-debug.aab \
              "$GITHUB_WORKSPACE/iris-android-v$VERSION-debug.aab"
          fi

      # jpackage cannot cross-compile: this only produces Linux packages.
      # When a Windows / macOS runner exists later, add a second build job
      # for it (jpackage picks the native type: msi on Windows, dmg on macOS).
      - name: Build desktop app-image + deb
        run: |
          VERSION=$(cat "$GITHUB_WORKSPACE/VERSION")
          [ -n "$VERSION" ] || { echo "::error::VERSION file is missing or empty"; exit 1; }
          cd app
          # Self-contained app image (JRE bundled via jlink).
          ./gradlew :desktopApp:jpackage -PappVersion="$VERSION"
          (cd desktopApp/build/jpackage && zip -qr \
            "$GITHUB_WORKSPACE/iris-desktop-linux-x64-v$VERSION.zip" iris)
          # .deb package (dpkg-deb ships with Ubuntu; fakeroot installed above).
          ./gradlew :desktopApp:jpackage -PjpackageType=deb -PappVersion="$VERSION"
          cp desktopApp/build/jpackage/*.deb \
            "$GITHUB_WORKSPACE/iris-desktop-linux-x64-v$VERSION.deb"

      - name: Create release + upload artifacts
        env:
          # Optional: create a personal access token (scope: Releases: write)
          # and store it as secret GITEA_TOKEN. Without it the workflow uses
          # the automatic GITHUB_TOKEN that Gitea Actions provides.
          RELEASE_TOKEN: ${{ secrets.GITEA_TOKEN }}
        run: |
          set -euo pipefail
          SERVER="${GITEA_SERVER_URL:-$GITHUB_SERVER_URL}"
          REPO="${GITEA_REPOSITORY:-$GITHUB_REPOSITORY}"
          TOKEN="${RELEASE_TOKEN:-$GITHUB_TOKEN}"
          VERSION=$(cat "$GITHUB_WORKSPACE/VERSION")
          # The dispatch input is a single-line field; turn literal \n into real newlines.
          CHANGELOG=$(jq -r '.inputs.changelog // ""' "$GITHUB_EVENT_PATH" | sed 's/\\n/\n/g')
          TAG="v$VERSION"
          API="$SERVER/api/v1/repos/$REPO"
          AUTH="Authorization: token $TOKEN"

          # curl wrapper: on HTTP >= 400, print the response body (Gitea's error
          # message) before failing — plain `curl -f` hides it (exit 22).
          api() {
            local code body
            body=$(mktemp)
            code=$(curl -s -o "$body" -w '%{http_code}' "$@") || { cat "$body"; rm -f "$body"; return 1; }
            if [ "${code:0:1}" != "2" ]; then
              echo "API error $code: $(cat "$body")" >&2
              rm -f "$body"
              return 1
            fi
            cat "$body"
            rm -f "$body"
          }

          # Re-run safety: drop a previous release AND its tag for this version.
          # (Gitea's DELETE /releases/:id does NOT remove the tag; a leftover tag
          # makes the POST below fail with 409.)
          OLD_ID=$(api -H "$AUTH" "$API/releases/tags/$TAG" | jq -r '.id // empty') || true
          if [ -n "$OLD_ID" ]; then
            api -X DELETE -H "$AUTH" "$API/releases/$OLD_ID" > /dev/null
          fi
          api -X DELETE -H "$AUTH" "$API/tags/$TAG" > /dev/null || true

          # Gitea creates the tag at the default branch HEAD automatically.
          RELEASE_ID=$(api -X POST -H "$AUTH" -H "Content-Type: application/json" \
            "$API/releases" \
            -d "$(jq -n --arg tag "$TAG" --arg title "Iris $VERSION" --arg body "$CHANGELOG" \
                 '{tag_name:$tag, title:$title, body:$body}')" \
            | jq -r .id)
          echo "Created release $TAG (id $RELEASE_ID)"

          for f in "$GITHUB_WORKSPACE"/iris-android-v* "$GITHUB_WORKSPACE"/iris-desktop-*; do
            [ -f "$f" ] || continue
            echo "Uploading $(basename "$f")"
            # Forgejo-style API: release assets live under /assets, not /attachments.
            api -X POST -H "$AUTH" -F "attachment=@$f" \
              "$API/releases/$RELEASE_ID/assets" > /dev/null
          done
          echo "Done: $SERVER/$REPO/releases/tag/$TAG"

---

4. EDITS to existing Gradle files

Note (versioning): the versionName / appVersion lines shown below have since been changed to read the repo-root VERSION file (single source of truth; -PappVersion still overrides in CI). See .gitea/workflows/release.yml and gateway-plugin/version.py.

4a. app/androidApp/build.gradle.kts

Change 1 — in defaultConfig, replace:

        versionName = "0.1.0"

with:

        // CI passes -PappVersion=<version> (release workflow); local builds
        // keep the default.
        versionName = (project.findProperty("appVersion") as? String) ?: "0.1.0"

Change 2 — inside the android { } block, right after the buildTypes { } block, add:

    // CI release signing: .gitea/workflows/release.yml restores a keystore
    // from Gitea secrets and exports ANDROID_KEYSTORE_* env vars (see
    // scripts/make_release_keystore.sh). Without them the release build stays
    // unsigned and the workflow falls back to a debug APK.
    val ciKeystore = System.getenv("ANDROID_KEYSTORE_FILE")
    if (ciKeystore != null) {
        signingConfigs {
            create("release") {
                storeFile = file(ciKeystore)
                storePassword = System.getenv("ANDROID_KEYSTORE_PASSWORD")
                keyAlias = System.getenv("ANDROID_KEY_ALIAS")
                keyPassword = System.getenv("ANDROID_KEY_PASSWORD")
            }
        }
        buildTypes {
            release {
                signingConfig = signingConfigs.getByName("release")
            }
        }
    }

4b. app/desktopApp/build.gradle.kts

Change 1 — near the top (after val arch = ...), add:

// CI passes -PappVersion=<version> (release workflow); local builds keep the
// default. jpackage requires a plain semver (no leading "v").
val appVersion = (project.findProperty("appVersion") as? String) ?: "0.1.0"

Change 2 — in the jpackage Exec task's commandLine(...), replace:

        "--app-version", "0.1.0",

with:

        "--app-version", appVersion,

---

5. NEW FILE: scripts/make_release_keystore.sh (Android signing, one-time)

This is the noob-friendly signing setup. Run it once on your machine:

scripts/make_release_keystore.sh

It generates a keystore with random passwords and prints the four values to paste into Gitea. Then create the secrets in Gitea → repo → Settings → Actions → Secrets:

Secret	Value
ANDROID_KEYSTORE_BASE64	the long base64 blob the script prints
ANDROID_KEYSTORE_PASSWORD	printed by the script
ANDROID_KEY_ALIAS	iris
ANDROID_KEY_PASSWORD	printed by the script

Until the secrets exist, the release workflow still works but ships a debug APK (installable, but not suitable for updates).

#!/usr/bin/env bash
# One-time setup: create the Android release keystore and print the values to
# paste into Gitea (repo -> Settings -> Actions -> Secrets).
#
# Usage:  scripts/make_release_keystore.sh [output-file]
#         (default: ~/iris-release.keystore)
#
# WARNING: back up the keystore file immediately. If it is lost, the app can
# never be updated on users' phones (a new key = a brand-new app as far as
# Android is concerned).
set -euo pipefail

OUT="${1:-$HOME/iris-release.keystore}"
if [ -e "$OUT" ]; then
  echo "Refusing to overwrite existing file: $OUT" >&2
  exit 1
fi

STORE_PASS="$(openssl rand -base64 18 | tr -d '/+=')"
KEY_PASS="$(openssl rand -base64 18 | tr -d '/+=')"

keytool -genkeypair -v \
  -keystore "$OUT" -storetype PKCS12 \
  -alias iris -keyalg RSA -keysize 2048 -validity 10000 \
  -storepass "$STORE_PASS" -keypass "$KEY_PASS" \
  -dname "CN=Iris Release, OU=Mobile, O=Iris, C=DE"

echo
echo "Keystore written to: $OUT"
echo ">>> Back it up NOW (password manager / cloud storage). <<<"
echo
echo "Add these four secrets in Gitea (repo -> Settings -> Actions -> Secrets):"
echo
echo "  ANDROID_KEYSTORE_BASE64   = $(base64 -w0 "$OUT")"
echo
echo "  ANDROID_KEYSTORE_PASSWORD = $STORE_PASS"
echo "  ANDROID_KEY_ALIAS         = iris"
echo "  ANDROID_KEY_PASSWORD      = $KEY_PASS"

Don't forget: chmod +x scripts/make_release_keystore.sh

---

6. Prerequisites / checks before the first run

1. act_runner must be registered on gitea.zephyre.one with the label ubuntu-latest (that's what both workflows request). Check under Gitea → (your user or the org) → Actions → Runners.
2. The runner needs internet access (GitHub, Google, Maven Central, Gradle).
3. No Gitea secrets are required — but add the four keystore secrets from §5 for a signed APK, and optionally a GITEA_TOKEN (Releases: write) if the automatic GITHUB_TOKEN doesn't have release permission.

7. Using it

• CI: pushes to master / PRs run automatically.
• Release: repo → Actions → Release → Run workflow → enter version (e.g. 0.2.0) + changelog → start. The release appears at https://gitea.zephyre.one/ARIA/iris_x_hermes/releases/tag/v0.2.0 with:
  • iris-android-v0.2.0.apk (signed, or -debug without keystore secrets)
  • iris-desktop-linux-x64-v0.2.0.zip (app image, JRE bundled)
  • iris-desktop-linux-x64-v0.2.0.deb
• Re-running with the same version replaces the old release (old tag + attachments are deleted first).

8. Later: Windows / macOS desktop builds

When the Windows VM / MacBook runner exists:

1. Register act_runner on that machine (labels e.g. windows-latest, macos-latest).
2. In release.yml, copy the desktop job, change runs-on, and adjust the artifact names (iris-desktop-windows-x64-…, iris-desktop-macos-…). jpackage then produces msi/dmg natively — no other changes needed.
3. Bump the pinned hermes-agent SHA in both workflows whenever you update the local hermes-agent/ checkout (git -C hermes-agent rev-parse HEAD).