TF-1302 chore(ci): enable SSH access for private Flutter deps and standardize workflows

Author: dab246

.github/workflows/analyze-test.yaml

@@ -29,36 +29,55 @@ jobs:
       fail-fast: false
 
     steps:
+      # 🔄 Checkout repository
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup flutter
+      # 🧰 Setup SSH (required for private git@ dependencies)
+      - name: Set up SSH for private Git dependencies
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+
+      # ⚙️ Add GitHub to known hosts (avoid "Host key verification failed")
+      - name: Add GitHub to known hosts
+        run: |
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+
+      # 🚀 Setup Flutter SDK
+      - name: Setup Flutter
         uses: subosito/flutter-action@v2
         with:
           flutter-version: ${{ env.FLUTTER_VERSION }}
           channel: "stable"
           cache: true
           cache-key: "deps-${{ hashFiles('**/pubspec.lock') }}"
-          cache-path: ${{ runner.tool_cache }}/flutter # optional, change this to specify the cache path
+          cache-path: ${{ runner.tool_cache }}/flutter
 
+      # 🔥 Setup Firebase environment (if required by tests)
       - name: Setup Firebase env
         env:
           FIREBASE_ENV: ${{ secrets.FIREBASE_ENV }}
         run: ./scripts/setup-firebase.sh
 
+      # 🧱 Prebuild step (runs flutter pub get + build_runner + intl generation)
       - name: Run prebuild
         run: ./scripts/prebuild.sh
 
-      - name: Analyze
+      # 🧩 Run Flutter static analysis
+      - name: Analyze Dart code
         uses: zgosalvez/github-actions-analyze-dart@v1
 
-      - name: Test
+      # 🧪 Run tests for each module in matrix
+      - name: Run tests
         env:
           MODULES: ${{ matrix.modules }}
         run: ./scripts/test.sh
 
+      # 📤 Upload test reports (always, even on failure)
       - name: Upload test reports
-        if: success() || failure() # Always upload report
+        if: success() || failure()
         uses: actions/upload-artifact@v4
         with:
           name: test-reports-${{ matrix.modules }}

.github/workflows/build.yaml

@@ -19,62 +19,88 @@ jobs:
           - os: android
             runner: ubuntu-latest
           - os: ios
-            runner: macos-14 # Use macos-14 runners because Xcode 16 only exists on macOS 14+.
+            runner: macos-14 # Xcode 16 is only available on macOS 14+
     environment: dev
 
     steps:
+      # 🧰 Setup SSH (required because some dependencies use git@ URLs)
+      - name: Set up SSH for private Git dependencies
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+
+      # ⚙️ Add GitHub to known hosts to avoid "Host key verification failed"
+      - name: Add GitHub to known hosts
+        run: |
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+
+      # 📦 Checkout the repository (uses HTTPS by default, SSH key not needed)
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Setup flutter
+      # 🚀 Setup Flutter environment
+      - name: Setup Flutter
         uses: subosito/flutter-action@v2
         with:
           flutter-version: ${{ env.FLUTTER_VERSION }}
           channel: "stable"
           cache: true
-          cache-key: deps-${{ hashFiles('**/pubspec.lock') }} # optional, change this to force refresh cache
-          cache-path: ${{ runner.tool_cache }}/flutter # optional, change this to specify the cache path
+          cache-key: deps-${{ hashFiles('**/pubspec.lock') }}
+          cache-path: ${{ runner.tool_cache }}/flutter
+
+      # 🧹 Clean Flutter pub cache to avoid stale SSH clones
+      - name: Clean pub cache
+        run: flutter pub cache clean || true
 
+      # 💎 Setup Fastlane (for both Android and iOS builds)
       - name: Setup Fastlane
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: "3.3"
           bundler-cache: true
           working-directory: ${{ matrix.os }}
 
+      # 🔥 Setup Firebase environment variables
       - name: Setup Firebase env
         env:
           FIREBASE_ENV: ${{ secrets.FIREBASE_ENV }}
         run: ./scripts/setup-firebase.sh
 
+      # ☕️ Setup Java for Android builds
       - name: Setup Java
         if: matrix.os == 'android'
         uses: actions/setup-java@v4
         with:
           distribution: "temurin"
           java-version: "17"
 
+      # 🍏 Select the required Xcode version for iOS builds
       - name: Select Xcode version
         if: matrix.os == 'ios'
         uses: maxim-lobanov/setup-xcode@v1
         with:
           xcode-version: ${{ env.XCODE_VERSION }}
 
+      # ⚙️ Setup iOS environment (Fastlane match, certificates, etc.)
       - name: Setup iOS environment
         if: matrix.os == 'ios'
         run: ../scripts/setup-ios.sh
         working-directory: ${{ matrix.os }}
 
+      # 🛠️ Run prebuild tasks (code generation, assets, etc.)
       - name: Run prebuild
         run: ./scripts/prebuild.sh
 
+      # 🧱 Build development binaries (Android .apk / iOS .ipa)
       - name: Build
         env:
           MATCH_PASSWORD: ${{ secrets.MATCH_PASSWORD }}
           APPLE_CERTIFICATES_SSH_KEY: ${{ secrets.APPLE_CERTIFICATES_SSH_KEY }}
         run: ../scripts/build-dev.sh
         working-directory: ${{ matrix.os }}
 
+      # 📤 Upload build artifacts (APK or IPA)
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
         with:

.github/workflows/gh-pages.yaml

@@ -3,7 +3,7 @@ on:
     paths:
       - "**/*.dart"
 
-name: Deploy PR on Github Pages
+name: Deploy PR on GitHub Pages
 
 env:
   FLUTTER_VERSION: 3.32.8
@@ -20,7 +20,7 @@ jobs:
       url: ${{ steps.configure.outputs.URL }}
 
     steps:
-      # 🧹 Free up space before building
+      # 🧹 Free up disk space before building to avoid "No space left" errors
       - name: Free up disk space before build
         run: |
           echo "=== Disk space before cleanup ==="
@@ -33,36 +33,52 @@ jobs:
           echo "=== Disk space after cleanup ==="
           df -h
 
-      # 🔄 Checkout code
+      # 🔄 Checkout repository
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      # 🧰 Setup Flutter
+      # 🧰 Setup SSH for private Git dependencies (required for [email protected])
+      - name: Set up SSH for private Git dependencies
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+
+      # ⚙️ Add GitHub to known hosts to prevent "Host key verification failed"
+      - name: Add GitHub to known hosts
+        run: |
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+
+      # 🚀 Setup Flutter SDK
       - name: Setup Flutter
         uses: subosito/flutter-action@v2
         with:
           flutter-version: ${{ env.FLUTTER_VERSION }}
           channel: "stable"
           cache: true
-          cache-key: deps-${{ hashFiles('**/pubspec.lock') }} # optional, change this to force refresh cache
-          cache-path: ${{ runner.tool_cache }}/flutter # optional, change this to specify the cache path
+          cache-key: deps-${{ hashFiles('**/pubspec.lock') }}
+          cache-path: ${{ runner.tool_cache }}/flutter
 
       # 🧹 Clean Flutter cache before building
       - name: Flutter clean
         run: flutter clean
 
-      # 📦 Run prebuild (if any)
+      # 🧹 Optionally clean pub cache to avoid stale SSH clones
+      - name: Clean pub cache
+        run: flutter pub cache clean || true
+
+      # 📦 Run prebuild script (if any, e.g. code generation, assets)
       - name: Run prebuild
         run: ./scripts/prebuild.sh
 
-      # ⚙️ Configure environment for PR
+      # ⚙️ Configure web environment for PR deployment
       - name: Configure environments
         id: configure
         env:
           FOLDER: ${{ github.event.pull_request.number }}
         run: ./scripts/configure-web-environment.sh
 
-      # 🧱 Build Flutter Web (release)
+      # 🧱 Build Flutter Web (release mode)
       - name: Build Web (Release)
         env:
           FOLDER: ${{ github.event.pull_request.number }}
@@ -73,7 +89,7 @@ jobs:
           echo "=== Disk usage after build ==="
           df -h
 
-      # 🚀 Deploy to GitHub Pages
+      # 🚀 Deploy to GitHub Pages (each PR has its own subfolder)
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
@@ -82,7 +98,7 @@ jobs:
           keep_files: true
           publish_dir: "build/web"
 
-      # 🧹 Clean up after build to save space
+      # 🧹 Cleanup after build to free up disk space
       - name: Cleanup after deploy
         if: always()
         run: |
@@ -91,7 +107,7 @@ jobs:
           echo "=== Disk usage after cleanup ==="
           df -h
 
-      # 💬 Create or update comments on PR
+      # 💬 Find existing deployment comment on PR (if exists)
       - name: Find deployment comment
         uses: peter-evans/find-comment@v3
         id: fc
@@ -100,6 +116,7 @@ jobs:
           issue-number: ${{ github.event.pull_request.number }}
           body-includes: "This PR has been deployed to"
 
+      # 💬 Create or update the comment with the PR deployment URL
       - name: Create or update deployment comment
         uses: peter-evans/create-or-update-comment@v4
         with:

.github/workflows/image.yaml

@@ -8,16 +8,31 @@ on:
 name: Build Docker images
 
 jobs:
+  # 🧩 Build and push the development Docker image (triggered on master branch)
   build-dev-image:
     name: Build development image
     if: github.ref_type == 'branch' && github.ref_name == 'master'
     runs-on: ubuntu-latest
     environment: dev
 
     steps:
+      # 🧰 Setup SSH (needed for private git@ dependencies inside Docker build)
+      - name: Set up SSH for private Git dependencies
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+
+      # ⚙️ Add GitHub to known hosts (avoid host verification errors)
+      - name: Add GitHub to known hosts
+        run: |
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+
+      # ⚙️ Setup Docker Buildx (multi-platform builder)
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      # 🧩 Generate Docker image metadata (tags, labels)
       - name: Docker metadata
         id: meta
         uses: docker/metadata-action@v5
@@ -28,41 +43,58 @@ jobs:
           tags: |
             type=ref,event=branch
 
+      # 🔐 Login to Docker Hub
       - name: Login to Docker Hub
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      # 🔐 Login to GitHub Container Registry (GHCR)
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # 🏗️ Build and push the development image (with SSH forwarding)
       - name: Build and push image
         uses: docker/build-push-action@v5
         with:
           push: true
-          platforms: "linux/amd64,linux/arm64"
-          cache-from: |
-            type=gha
-          cache-to: |
-            type=gha
+          ssh: default # ✅ Forward SSH key into Docker for private git@ dependencies
+          platforms: linux/amd64,linux/arm64
+          cache-from: type=gha
+          cache-to: type=gha
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
 
+  # 🚀 Build and push the production (release) Docker image (triggered on version tags)
   build-release-image:
     name: Build release image
     if: github.ref_type == 'tag' && startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     environment: prod
 
     steps:
+      # 🧰 Setup SSH (needed for private git@ dependencies inside Docker build)
+      - name: Set up SSH for private Git dependencies
+        uses: webfactory/[email protected]
+        with:
+          ssh-private-key: ${{ secrets.SSH_KEY }}
+
+      # ⚙️ Add GitHub to known hosts
+      - name: Add GitHub to known hosts
+        run: |
+          mkdir -p ~/.ssh
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+
+      # ⚙️ Setup Docker Buildx
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@v3
 
+      # 🧩 Generate Docker image metadata for release tags
       - name: Docker metadata
         id: meta
         uses: docker/metadata-action@v5
@@ -74,27 +106,29 @@ jobs:
             type=ref,event=tag
             type=raw,value=release
 
+      # 🔐 Login to Docker Hub
       - name: Login to Docker Hub
         uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
+      # 🔐 Login to GitHub Container Registry (GHCR)
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      # 🏗️ Build and push the release image (with SSH forwarding)
       - name: Build and push image
         uses: docker/build-push-action@v5
         with:
           push: true
-          platforms: "linux/amd64,linux/arm64"
-          cache-from: |
-            type=gha
-          cache-to: |
-            type=gha
+          ssh: default # ✅ Enable SSH forwarding during Docker build
+          platforms: linux/amd64,linux/arm64
+          cache-from: type=gha
+          cache-to: type=gha
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}