📱 EAS Workflows Integration Guide (LEGACY)

Legacy

This document describes an older EAS Workflows-based pipeline. The current pipeline is documented in deployment/mobile-deployment-guide.

🎯 Overview

AttuneLogic Mobile uses a hybrid deployment strategy that combines:

• GitHub Actions for PR-based approval workflow
• EAS Workflows for optimized mobile build and deployment operations

This approach provides the best of both worlds: familiar PR approval flow with mobile-optimized build intelligence.

Why EAS Workflows?

EAS Workflows provide automatic fingerprinting, intelligent repack optimization, and pre-packaged jobs specifically designed for React Native/Expo apps. This results in faster builds and simpler maintenance compared to custom scripts.

---

🏗️ Architecture

graph TD
    A[GitHub: Push to Feature Branch] --> B[GitHub Actions: Build & Validate]
    B --> C[GitHub Actions: Create PR to Beta]
    C --> D[Review & Merge PR]
    D --> E[GitHub Actions: Trigger EAS Workflow]
    E --> F[EAS Workflow: deploy-beta.yml]
    F --> G[EAS: Generate Fingerprint]
    G --> H{Native Changes?}
    H -->|No| I[EAS: Repack Existing Build 2-5min]
    H -->|Yes| J[EAS: Build Native 15-30min]
    I --> K[EAS: Publish OTA Update]
    J --> K
    K --> L[EAS: Send Slack Notification]
    L --> M[GitHub Actions: Create PR to Alpha]

---

🔄 Workflow Components

1. GitHub Actions (Orchestration)

Location: .github/workflows/mobile-deploy-eas.yml

Responsibilities:

• ✅ Run validation and tests
• ✅ Create and manage PRs
• ✅ Trigger EAS Workflows
• ✅ Handle version bumping
• ✅ Manage Git operations

2. EAS Workflows (Execution)

Location: .eas/workflows/

• deploy-beta.yml
• deploy-alpha.yml
• deploy-production.yml

Responsibilities:

• ✅ Generate fingerprints (detect native changes)
• ✅ Check for existing compatible builds
• ✅ Repack or build based on changes
• ✅ Submit to TestFlight/Play Store
• ✅ Publish OTA updates
• ✅ Send notifications

---

📋 Pre-packaged Jobs

EAS Workflows come with built-in job types that we use:

fingerprint - Native Change Detection

fingerprint:
  type: fingerprint
  params:
    platform: all

Output: Generates hashes for iOS and Android native layers

get-build - Find Compatible Build

android_get_build:
  type: get-build
  params:
    fingerprint_hash: ${{ needs.fingerprint.outputs.android_fingerprint_hash }}
    platform: android

Output: build_id if compatible build exists

repack - Fast JS Update

android_repack:
  type: repack
  params:
    build_id: ${{ needs.android_get_build.outputs.build_id }}

Time: 2-5 minutes (fast!)
Use Case: JS-only changes

build - Full Native Build

android_build:
  type: build
  params:
    platform: android
    profile: beta

Time: 15-30 minutes
Use Case: Native changes required

update - OTA Deployment

publish_update:
  type: update
  params:
    branch: beta
    message: 'Beta OTA update'

Time: < 1 minute
Use Case: Deploy JS changes to users

testflight - iOS TestFlight Submission

ios_submit:
  type: testflight
  params:
    build_id: ${{ needs.ios_build.outputs.build_id }}

Use Case: Submit iOS builds to TestFlight

submit - App Store/Play Store Submission

android_submit:
  type: submit
  params:
    build_id: ${{ needs.android_build.outputs.build_id }}
    platform: android
    track: internal

Use Case: Submit to App/Play Store

slack - Team Notifications

notify:
  type: slack
  params:
    webhook_url: ${{ secrets.SLACK_WEBHOOK_URL }}
    message: 'Deployment complete!'

Use Case: Send deployment notifications

require-approval - Manual Gate

approval:
  type: require-approval
  params:
    message: 'Please confirm production deployment'

Use Case: Production safety gate

---

🚀 Deployment Flow

Beta Deployment

1. Developer merges PR to beta
2. GitHub Actions: Trigger EAS Workflow
3. EAS Workflow (deploy-beta.yml):
   ├─ Generate fingerprint
   ├─ Check for existing builds
   ├─ Decision:
   │  ├─ Repack (if compatible build exists) ~2-5 min
   │  └─ Build (if no compatible build) ~15-30 min
   ├─ Publish OTA update
   └─ Send Slack notification
4. GitHub Actions: Create PR beta → alpha

Alpha Deployment (TestFlight)

1. Merge PR to alpha
2. GitHub Actions: Trigger EAS Workflow
3. EAS Workflow (deploy-alpha.yml):
   ├─ Generate fingerprint
   ├─ Check for existing builds
   ├─ Repack or Build
   ├─ Submit iOS to TestFlight
   ├─ Submit Android to Play Internal
   ├─ Publish OTA update
   └─ Send Slack notification
4. GitHub Actions: Create PR alpha → main

Production Deployment

1. Merge PR to main
2. GitHub Actions:
   ├─ Bump version (patch/minor/major)
   └─ Trigger EAS Workflow
3. EAS Workflow (deploy-production.yml):
   ├─ Generate fingerprint
   ├─ Build fresh binaries (recommended)
   ├─ Submit iOS to App Store
   ├─ Submit Android to Play Store Production
   ├─ Publish OTA update
   ├─ Send Slack notification
   └─ Require manual approval
4. GitHub Actions: Create sync PR main → alpha

---

⚡ Performance Comparison

Scenario	Without EAS Workflows	With EAS Workflows
JS-only changes	OTA Update: 2-5 min	Repack: 2-5 min (same speed)
Native changes	Full Build: 15-30 min	Full Build: 15-30 min (same)
Find existing build	Manual script	Automatic ✅
Fingerprint generation	Manual implementation	Built-in ✅
TestFlight submission	Custom script	Pre-packaged ✅
E2E Testing	Custom setup	Maestro built-in ✅

---

🔧 Configuration

Required GitHub Secrets

Secret	Purpose	Required
EXPO_TOKEN	EAS authentication	✅ Yes
EXPO_ACCOUNT	Your Expo account slug	✅ Yes
SLACK_WEBHOOK_URL	Slack notifications	❌ Optional
GITHUB_TOKEN	PR creation	✅ Auto-provided

Getting Your EXPO_TOKEN

1. Visit: https://expo.dev/accounts/[your-account]/settings/access-tokens
2. Click "Create token"
3. Name: github-actions-mobile
4. Scopes: Select all
5. Add to GitHub: Settings → Secrets → Actions → New repository secret

Finding Your EXPO_ACCOUNT

Your account slug is in your Expo dashboard URL:

https://expo.dev/accounts/[your-account-slug]/projects/
                          ^^^^^^^^^^^^^^^^^^^^

---

📁 File Structure

attunelogic-mobile/
├── .eas/
│   └── workflows/
│       ├── deploy-beta.yml        # Beta deployment workflow
│       ├── deploy-alpha.yml       # Alpha deployment workflow
│       └── deploy-production.yml  # Production deployment workflow
│
├── .github/
│   ├── workflows/
│   │   └── mobile-deploy-eas.yml  # GitHub Actions orchestration
│   └── actions/
│       └── create-pr/             # Reusable PR creation action
│
└── eas.json                       # EAS build/submit configuration

---

🎮 Usage Examples

Standard Deployment (Automatic)

# 1. Create feature and push
git checkout -b feature/new-screen
git add . && git commit -m "feat: add new job details screen"
git push origin feature/new-screen

# 2. GitHub Actions creates PR to beta
# 3. Review and merge PR
# 4. EAS Workflow automatically:
#    - Generates fingerprint
#    - Repacks existing build (fast!)
#    - Publishes OTA update
#    - Creates PR to alpha

Force Native Build

# Add [build] flag to commit message
git commit -m "feat: add camera module [build]"
git push

# EAS Workflow will build fresh binaries instead of repack

Manual Workflow Dispatch

1. Go to GitHub → Actions → "Mobile Multi-Stage Deploy (EAS Workflows)"
2. Click "Run workflow"
3. Choose:
   • target_stage: beta / alpha / production
   • force_build: true (skip fingerprint check)

---

📊 Monitoring & Observability

Where to Monitor

1. GitHub Actions: https://github.com/[org]/attunelogic-mobile/actions

   • PR creation and orchestration
   • Version bumping
   • Git operations

2. EAS Dashboard: https://expo.dev/accounts/[account]/projects/attunelogic-mobile

   • Workflows: View EAS Workflow runs
   • Builds: View all builds and their status
   • Updates: View OTA updates and adoption
   • Submissions: Track App/Play Store submissions

3. Slack: Real-time notifications (if configured)

Reading EAS Workflow Logs

1. Visit EAS Dashboard → Workflows
2. Click on the workflow run
3. View each job's status:
   ✅ fingerprint: Completed in 30s
   ✅ android_get_build: Found build abc123
   ✅ android_repack: Completed in 2m 15s
   ✅ publish_update: Update published
   ✅ notify: Slack notification sent

---

🔍 Troubleshooting

EAS Workflow Not Triggering

Symptom: GitHub Actions completes but no EAS Workflow runs

Solutions:

1. ✅ Verify EXPO_TOKEN secret is set
2. ✅ Check EAS CLI is latest version
3. ✅ Ensure .eas/workflows/ files exist
4. ✅ Check EAS dashboard for errors

Fingerprint Mismatch

Symptom: "No compatible build found" even for JS changes

Solutions:

1. ✅ Check if native dependencies changed
2. ✅ Verify app.config.js hasn't changed
3. ✅ Force new build with [build] flag
4. ✅ Check EAS build logs for fingerprint details

Repack Failing

Symptom: Repack job fails with error

Solutions:

1. ✅ Ensure original build completed successfully
2. ✅ Verify runtime version hasn't changed
3. ✅ Check if build profile matches
4. ✅ Try forcing a fresh build

TestFlight/Play Submission Fails

Symptom: Submit job fails in EAS Workflow

Solutions:

1. ✅ Verify Apple/Google credentials are configured
2. ✅ Check App Store Connect / Play Console for errors
3. ✅ Ensure build profile is store distribution
4. ✅ Check EAS submission logs for details

---

🆚 Comparison: Before vs After

Before (Pure GitHub Actions)

deploy-beta:
  steps:
    # Manual fingerprint check
    - name: Check native changes
      run: |
        # Custom bash script (~50 lines)
        # Check ios/, android/, package.json, etc.
    
    # Conditional build
    - name: Build if needed
      if: needs_build == 'true'
      run: eas build --profile beta
    
    # OTA update
    - name: Push update
      if: needs_build == 'false'
      run: eas update --branch beta

Issues:

• ❌ Manual fingerprint logic (error-prone)
• ❌ No repack optimization
• ❌ Custom scripts to maintain
• ❌ More complex YAML

After (EAS Workflows)

# In GitHub Actions
deploy-beta:
  steps:
    - name: Trigger EAS Workflow
      run: npx eas-cli workflow:run deploy-beta.yml

# In EAS Workflow
jobs:
  fingerprint:
    type: fingerprint
  
  android_get_build:
    type: get-build
  
  android_repack:
    type: repack

Benefits:

• ✅ Automatic fingerprinting
• ✅ Built-in repack optimization
• ✅ Pre-packaged jobs
• ✅ Simpler configuration

---

🎯 Best Practices

1. Let EAS Workflows Handle Build Logic

# ✅ Good: Let EAS decide
- name: Trigger workflow
  run: npx eas-cli workflow:run deploy-beta.yml

# ❌ Avoid: Manual build decisions in GitHub Actions
- name: Manual check
  run: |
    if [ native_changes ]; then
      eas build...

2. Use Fingerprinting for All Environments

# Always start with fingerprint job
fingerprint:
  type: fingerprint
  params:
    platform: all

3. Prefer Repack Over Full Builds

# Let EAS Workflow decide based on fingerprint
android_repack:
  if: ${{ needs.android_get_build.outputs.build_id }}
  type: repack

4. Monitor EAS Dashboard Regularly

• Check workflow success rates
• Review build times
• Track OTA adoption
• Monitor submission status

5. Use [build] Flag Sparingly

# Only for actual native changes
git commit -m "feat: add camera [build]"

# Not for every deployment
git commit -m "fix: button style"  # No [build] needed

---

📚 Related Documentation

• Mobile Deployment Guide - Complete deployment process
• Mobile Quick Reference - Quick commands and workflows
• EAS Workflows Official Docs - Expo documentation
• EAS Build Documentation - Build configuration
• EAS Submit Documentation - App submission

---

🎉 Summary

The hybrid approach with EAS Workflows provides:

✅ GitHub PR approval flow (familiar workflow)
✅ Automatic fingerprinting (no manual scripts)
✅ Intelligent repack (2-5 min for JS changes)
✅ Pre-packaged jobs (less maintenance)
✅ Built-in TestFlight/Play submission (simplified)
✅ Better monitoring (expo.dev dashboard)
✅ Consistent with API/Service (same PR pattern)
✅ Mobile-optimized (designed for React Native/Expo)

This setup gives you production-ready mobile CI/CD that's both powerful and maintainable! 🚀