# 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

{% hint style="info" %}
**Note**: App names are **case-sensitive** and must match exactly as shown in the FinalRun dashboard.
{% endhint %}

{% embed url="<https://youtu.be/IqywnR-UcAo>" %}

### 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

```yaml
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

```yaml
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
```