GitHub Actions Setup

Configure automated builds and Firebase App Distribution

Overview

This guide explains how to set up GitHub Actions for automated builds and distribution via Firebase App Distribution.

What you'll get: Automatic builds for Android (APK) and iOS (IPA) that are distributed to testers via Firebase App Distribution whenever you push to the develop branch.

Available Workflows

flutter-ci.yml

Runs on every PR and push to main/develop. Executes tests, linting, and debug builds.

deploy-dev.yml

Builds release versions and deploys to Firebase App Distribution for testing.

Step 1: Create Firebase Service Account

You need a service account with permissions to upload to Firebase App Distribution.

  1. Go to Firebase Console
  2. Select your project
  3. Go to Project Settings (gear icon)
  4. Click Service accounts tab
  5. Click Generate new private key
  6. Download the JSON file
Security: This JSON file contains sensitive credentials. Never commit it to your repository!

Step 2: Configure GitHub Secrets

Go to your GitHub repository → Settings → Secrets and variables → Actions → New repository secret

Firebase Secrets

Secret Name Description Where to Find
FIREBASE_SERVICE_ACCOUNT_JSON Service account JSON (entire file content) Downloaded in Step 1
FIREBASE_API_KEY_ANDROID Firebase API Key for Android Firebase Console → Project Settings → Your apps → Android
FIREBASE_API_KEY_IOS Firebase API Key for iOS Firebase Console → Project Settings → Your apps → iOS
FIREBASE_PROJECT_ID Firebase Project ID Firebase Console → Project Settings
FIREBASE_APP_ID_ANDROID Android App ID Firebase Console → Project Settings → Your apps → Android
FIREBASE_APP_ID_IOS iOS App ID Firebase Console → Project Settings → Your apps → iOS
FIREBASE_MESSAGING_SENDER_ID Cloud Messaging Sender ID Firebase Console → Project Settings → Cloud Messaging
FIREBASE_STORAGE_BUCKET Storage bucket URL Firebase Console → Storage (e.g., your-project.appspot.com)

Google Services Secrets

Secret Name Description
GOOGLE_SERVICES_JSON Entire content of google-services.json
GOOGLE_SERVICE_INFO_PLIST Entire content of GoogleService-Info.plist
GOOGLE_MAPS_API_KEY_ANDROID Google Maps API key for Android
GOOGLE_MAPS_API_KEY_IOS Google Maps API key for iOS
GOOGLE_MAPS_API_KEY_WEB Google Maps API key for Web
GEOCODING_API_KEY Geocoding API key

iOS Signing Secrets

Secret Name Description
IOS_DISTRIBUTION_CERTIFICATE_P12 Base64 encoded .p12 distribution certificate
IOS_DISTRIBUTION_CERTIFICATE_PASSWORD Password for the .p12 certificate
IOS_PROVISIONING_PROFILE_BASE64 Base64 encoded Ad-Hoc provisioning profile
IOS_PROVISIONING_PROFILE_NAME Name of the provisioning profile
IOS_CODE_SIGN_IDENTITY Usually: "iPhone Distribution"
IOS_TEAM_ID Your Apple Developer Team ID
IOS_BUNDLE_ID App bundle identifier (e.g., com.missao.app.dev)

Other Secrets

Secret Name Description
ADMIN_PANEL_URL URL of your admin panel

Step 3: iOS Certificate Setup

To sign iOS builds, you need to create and export certificates from Apple Developer.

Create Distribution Certificate

  1. Go to Apple Developer
  2. Navigate to Certificates, IDs & Profiles → Certificates
  3. Click + to create a new certificate
  4. Select "Apple Distribution" (for App Store and Ad Hoc)
  5. Follow the instructions to create a CSR using Keychain Access
  6. Download the certificate and install it in Keychain

Export as .p12

  1. Open Keychain Access
  2. Find your certificate under "My Certificates"
  3. Right-click → Export
  4. Save as .p12 with a strong password
  5. Convert to base64: 
    base64 -i certificate.p12 | pbcopy
  6. Paste the output as IOS_DISTRIBUTION_CERTIFICATE_P12 secret

Create Ad-Hoc Provisioning Profile

  1. Go to Certificates, IDs & Profiles → Profiles
  2. Click + to create a new profile
  3. Select "Ad Hoc" under Distribution
  4. Select your App ID
  5. Select your distribution certificate
  6. Select devices for testing
  7. Name the profile and download
  8. Convert to base64: 
    base64 -i profile.mobileprovision | pbcopy
  9. Paste as IOS_PROVISIONING_PROFILE_BASE64 secret
Tip: Add all test devices to your Apple Developer account before creating the provisioning profile.

Step 4: Firebase App Distribution Setup

Create Tester Groups

  1. Go to Firebase Console
  2. Select your project → Release & Monitor → App Distribution
  3. Click "Testers & Groups" tab
  4. Click "Add group"
  5. Create a group named testers
  6. Add tester emails to the group
Important: The workflow uses the group name testers by default. Change it in the workflow file if you use a different name.

Step 5: Trigger the Workflow

Automatic Trigger

The workflow runs automatically when you push to the develop branch:

git checkout develop
git add .
git commit -m "feat: new feature"
git push origin develop

Manual Trigger

You can also trigger the workflow manually:

  1. Go to your GitHub repository
  2. Click "Actions" tab
  3. Select "Deploy DEV to Firebase App Distribution"
  4. Click "Run workflow"
  5. Choose the platform (Android, iOS, or both)
  6. Click "Run workflow" button

Troubleshooting

iOS build fails with signing error

Solutions:

  • Verify certificate and profile are not expired
  • Check that bundle ID matches in profile and workflow
  • Ensure all test devices are included in provisioning profile
  • Regenerate certificate and profile if needed

Firebase App Distribution upload fails

Solutions:

  • Verify service account has correct permissions
  • Check that App ID matches in Firebase Console
  • Ensure the "testers" group exists

Build fails with missing secrets

Solution: Double-check all required secrets are configured in GitHub repository settings. Secret names are case-sensitive.

Android build fails

Solutions:

  • Verify GOOGLE_SERVICES_JSON content is valid JSON
  • Check that all Firebase config values are correct
  • Ensure Flutter version matches in workflow

Quick Reference: All Secrets

# Firebase
FIREBASE_SERVICE_ACCOUNT_JSON
FIREBASE_API_KEY_ANDROID
FIREBASE_API_KEY_IOS
FIREBASE_PROJECT_ID
FIREBASE_APP_ID_ANDROID
FIREBASE_APP_ID_IOS
FIREBASE_MESSAGING_SENDER_ID
FIREBASE_STORAGE_BUCKET

# Google Services
GOOGLE_SERVICES_JSON
GOOGLE_SERVICE_INFO_PLIST
GOOGLE_MAPS_API_KEY_ANDROID
GOOGLE_MAPS_API_KEY_IOS
GOOGLE_MAPS_API_KEY_WEB
GEOCODING_API_KEY

# iOS Signing
IOS_DISTRIBUTION_CERTIFICATE_P12
IOS_DISTRIBUTION_CERTIFICATE_PASSWORD
IOS_PROVISIONING_PROFILE_BASE64
IOS_PROVISIONING_PROFILE_NAME
IOS_CODE_SIGN_IDENTITY
IOS_TEAM_ID
IOS_BUNDLE_ID

# Other
ADMIN_PANEL_URL

Next Steps

  1. Deployment - Deploy to App Store and Play Store
  2. FAQ - Common questions and troubleshooting