Github Actions

Automated your tests in the Finalrun cloud with Github Actions

Prerequisites

Before setting up GitHub Actions integration, ensure you have:

• FinalRun API Key - Obtain from your FinalRun dashboard

• App name - Obtain app name from FinalRun dashboard in Apps Section for the specific app

• GitHub Repository - With appropriate permissions to add secrets

Note: App names are case-sensitive and must match exactly as shown in the FinalRun dashboard.

Quick Setup

1. Add API Key to GitHub Secrets

1. Navigate to your repository on GitHub

2. Go to Settings → Secrets and variables → Actions

3. Click New repository secret

4. Add:

   • Name: FINALRUN_API_KEY

   • Secret: Your FinalRun API key from the dashboard

2. Full Example - Android

name: Android CI/CD with FinalRun

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  FINALRUN_API_KEY: ${{ secrets.FINALRUN_API_KEY }}
  # Use the exact app name as it appears in your FinalRun dashboard
  APP_NAME: "My Android App"

jobs:
  build-and-test:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

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

      - name: Cache Gradle dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: gradle-${{ runner.os }}-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: |
            gradle-${{ runner.os }}-

      - name: Grant execute permission to gradlew
        run: chmod +x gradlew

      - name: Build APK (Debug)
        run: ./gradlew assembleDebug

      - name: Upload APK as artifact
        uses: actions/upload-artifact@v4
        with:
          name: app-debug-apk
          path: app/build/outputs/apk/debug/app-debug.apk
          retention-days: 30

      - name: Install FinalRun CLI
        run: |
          echo "Installing FinalRun CLI..."
          rm -rf ~/.finalrun/bin/finalrun-cli
          curl -Ls "https://get-cli.finalrun.app/install.sh" | bash
          echo "$HOME/.finalrun/bin" >> $GITHUB_PATH
          export PATH="$HOME/.finalrun/bin:$PATH"
          which finalrun-cli
          finalrun-cli --version

      - name: Verify FinalRun CLI installation
        run: |
          finalrun-cli --version
          finalrun-cli --help

      - name: Run FinalRun Tests
        run: |
          echo "Running FinalRun tests..."
          finalrun-cli execute \
            --api-key="${FINALRUN_API_KEY}" \
            --app="${APP_NAME}=app/build/outputs/apk/debug/app-debug.apk" \
            --description="GitHub Actions - Commit: ${{ github.sha }}"

      - name: Test Results Summary
        if: always()
        run: |
          echo "## 🧪 Test Execution Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- **App**: $APP_NAME" >> $GITHUB_STEP_SUMMARY
          echo "- **Commit**: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Branch**: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Trigger**: ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          if [ "${{ job.status }}" == "success" ]; then
            echo "✅ **Status**: Tests passed successfully!" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ **Status**: Tests failed or encountered errors." >> $GITHUB_STEP_SUMMARY
          fi

Full Example - iOS

name: iOS Simulator CI/CD with FinalRun

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]
  workflow_dispatch:

env:
  FINALRUN_API_KEY: ${{ secrets.FINALRUN_API_KEY }}
  # Use the exact app name as it appears in your FinalRun dashboard
  APP_NAME: "My iOS App"
  # Replace with your actual Xcode scheme and workspace/project
  XCODE_SCHEME: YourAppScheme
  XCODE_WORKSPACE: YourProject.xcworkspace
  # If not using a workspace, comment out XCODE_WORKSPACE and use:
  # XCODE_PROJECT: YourProject.xcodeproj

jobs:
  build-and-test:
    runs-on: macos-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install CocoaPods
        run: |
          gem install cocoapods
          pod --version

      - name: Cache CocoaPods dependencies
        uses: actions/cache@v4
        with:
          path: |
            ~/Library/Caches/CocoaPods
            Pods
          key: ${{ runner.os }}-pods-${{ hashFiles('**/Podfile.lock') }}
          restore-keys: |
            ${{ runner.os }}-pods-

      - name: Install Pods
        run: pod install --repo-update

      - name: Build iOS App for Simulator
        run: |
          xcodebuild clean build \
            -workspace "${{ env.XCODE_WORKSPACE }}" \
            -scheme "${{ env.XCODE_SCHEME }}" \
            -sdk iphonesimulator \
            -configuration Debug \
            -derivedDataPath "build" \
            CODE_SIGNING_REQUIRED=NO \
            CODE_SIGN_IDENTITY=""

      - name: Locate built .app
        id: locate_app
        run: |
          APP_PATH=$(find build/Build/Products/Debug-iphonesimulator -name "*.app" -maxdepth 1 | head -n 1)
          if [ -z "$APP_PATH" ]; then
            echo "Error: .app bundle not found!"
            exit 1
          fi
          echo "Found app: $APP_PATH"
          echo "ios_app_path=$APP_PATH" >> "$GITHUB_OUTPUT"

      - name: Upload iOS .app as artifact
        uses: actions/upload-artifact@v4
        with:
          name: ios-simulator-app
          path: ${{ steps.locate_app.outputs.ios_app_path }}
          retention-days: 30

      - name: Install FinalRun CLI
        run: |
          echo "Installing FinalRun CLI..."
          rm -rf ~/.finalrun/bin/finalrun-cli
          curl -Ls "https://get-cli.finalrun.app/install.sh" | bash
          echo "$HOME/.finalrun/bin" >> $GITHUB_PATH
          export PATH="$HOME/.finalrun/bin:$PATH"
          which finalrun-cli
          finalrun-cli --version

      - name: Verify FinalRun CLI installation
        run: |
          finalrun-cli --version
          finalrun-cli --help

      - name: Run FinalRun Tests
        run: |
          echo "Running FinalRun tests..."
          finalrun-cli execute \
            --api-key="${FINALRUN_API_KEY}" \
            --app="${APP_NAME}=${{ steps.locate_app.outputs.ios_app_path }}" \
            --description="GitHub Actions - Commit: ${{ github.sha }}"

      - name: Test Results Summary
        if: always()
        run: |
          echo "## 🧪 Test Execution Summary" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "- **App**: $APP_NAME" >> $GITHUB_STEP_SUMMARY
          echo "- **Commit**: ${{ github.sha }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Branch**: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
          echo "- **Trigger**: ${{ github.event_name }}" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          if [ "${{ job.status }}" == "success" ]; then
            echo "✅ **Status**: Tests passed successfully!" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ **Status**: Tests failed or encountered errors." >> $GITHUB_STEP_SUMMARY
          fi