Automate Flutter App Builds With GitHub Actions

Let's dive into automating Flutter app builds using GitHub Actions. This guide provides a comprehensive walkthrough of how to set up continuous integration and continuous deployment (CI/CD) pipelines for your Flutter projects. By the end, you'll be equipped to automate the build, test, and deployment phases, ensuring a smoother and more efficient development workflow. Setting up automated workflows not only saves time but also reduces the risk of human error, leading to more reliable releases.

Why Use GitHub Actions for Flutter?

GitHub Actions offers a flexible and powerful platform for automating software workflows directly in your GitHub repository. For Flutter apps, this means you can automate everything from running tests to building and deploying your app to various platforms like Android and iOS. The beauty of GitHub Actions lies in its seamless integration with your existing GitHub workflow, making it easy to manage and monitor your CI/CD pipelines.

Here's why it's a game-changer:

Automation: Automate the build, test, and deployment processes, reducing manual effort and potential errors.
Efficiency: Speed up the development cycle with automated checks and deployments, allowing for faster feedback loops.
Reliability: Ensure consistent builds and deployments across different environments, minimizing surprises.
Integration: Seamlessly integrates with your GitHub repository, making it easy to manage and monitor your workflows.
Customization: Highly customizable workflows to fit the specific needs of your Flutter project.

Prerequisites

Before we get started, make sure you have the following:

A GitHub repository containing your Flutter project.
A basic understanding of Flutter development.
Familiarity with YAML syntax (as GitHub Actions workflows are defined in YAML files).
A Google Play Store or Apple App Store Connect account if you plan to automate deployment.

Step-by-Step Guide to Setting Up GitHub Actions for Flutter

Step 1: Create a Workflow File

First, you need to create a workflow file in your GitHub repository. This file defines the steps your GitHub Action will execute. Create a new file named main.yml inside the .github/workflows directory in your repository. If these directories don't exist, create them.

# .github/workflows/main.yml
name: Flutter CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '11'
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.0.0'
      - run: flutter pub get
      - run: flutter analyze
      - run: flutter test

Let's break down this workflow file:

name: The name of your workflow, which will be displayed in the GitHub Actions UI.
on: Specifies the events that trigger the workflow. In this case, it's triggered on push and pull requests to the main branch.
jobs: Defines the jobs to be executed. Here, we have a single job named build.
runs-on: Specifies the type of machine to run the job on. We're using ubuntu-latest for this example.
steps: A list of steps to be executed within the job. Each step uses an action or runs a shell command.
- actions/checkout@v3: This action checks out your repository to the runner.
- actions/setup-java@v3: Sets up Java, which is required for Flutter's Android build process.
- subosito/flutter-action@v2: Sets up Flutter with the specified version.
- flutter pub get: Runs flutter pub get to fetch the Flutter dependencies.
- flutter analyze: Runs flutter analyze to analyze the code for potential issues.
- flutter test: Runs flutter test to execute the Flutter tests.

Step 2: Configure Build for Android

To build your Flutter app for Android, you'll need to configure the necessary environment variables and signing configurations. Here’s how you can do it:

Set up Keystore: Generate a keystore file for signing your Android app. Store this file securely and add it to your repository's secrets.
Add Secrets: In your GitHub repository, go to Settings > Secrets > Actions and add the following secrets:
- KEYSTORE_FILE: The base64 encoded content of your keystore file.
- KEYSTORE_PASSWORD: The password for your keystore.
- KEY_ALIAS: The alias for your key.
- KEY_PASSWORD: The password for your key.
Update Workflow File: Modify your main.yml file to include the steps for building the Android app:

| Read Also : Wall Street Journal Bias: Fact Or Fiction?

# .github/workflows/main.yml
name: Flutter CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '11'
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.0.0'
      - run: flutter pub get
      - run: flutter analyze
      - run: flutter test
      - name: Create keystore directory
        run: mkdir -p android/key
      - name: Decode keystore file
        run: echo '${{ secrets.KEYSTORE_FILE }}' | base64 --decode > android/key/keystore.jks
      - name: Build Android App Bundle
        run: flutter build appbundle --release --build-number=${{ github.run_number }} --dart-define=APP_VERSION=${{ github.run_number }} --split-per-abi
        env:
          SIGNING_KEY_PATH: android/key/keystore.jks
          SIGNING_KEY_ALIAS: ${{ secrets.KEY_ALIAS }}
          SIGNING_KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }}
          SIGNING_STORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }}

Step 3: Configure Build for iOS

Building for iOS requires a macOS runner and some additional configuration. Here’s how to set it up:

Set up Code Signing: You'll need to configure code signing for your iOS app. This involves creating certificates and provisioning profiles in your Apple Developer account.
Add Secrets: Add the following secrets to your GitHub repository:
- APP_STORE_CONNECT_ISSUER_ID: The issuer ID for your App Store Connect API key.
- APP_STORE_CONNECT_KEY_ID: The key ID for your App Store Connect API key.
- APP_STORE_CONNECT_PRIVATE_KEY: The private key for your App Store Connect API key.
- CERTIFICATE_P12: Base64 encoded content of your Apple distribution certificate (.p12 file).
- CERTIFICATE_PASSWORD: Password for your Apple distribution certificate.
- PROVISIONING_PROFILE: Base64 encoded content of your provisioning profile.
Update Workflow File: Modify your main.yml file to include the steps for building the iOS app:

# .github/workflows/main.yml
name: Flutter CI/CD

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: 'zulu'
          java-version: '11'
      - uses: subosito/flutter-action@v2
        with:
          flutter-version: '3.0.0'
      - run: flutter pub get
      - run: flutter analyze
      - run: flutter test
      - name: Set up keychain
        run: |
          security create-keychain -p ${{ secrets.CERTIFICATE_PASSWORD }} flutter.keychain
          security default-keychain -s flutter.keychain
          security unlock-keychain -p ${{ secrets.CERTIFICATE_PASSWORD }} flutter.keychain
          security import certificate.p12 -k flutter.keychain -P ${{ secrets.CERTIFICATE_PASSWORD }} -T /usr/bin/codesign
      - name: Decode certificate
        run: echo '${{ secrets.CERTIFICATE_P12 }}' | base64 --decode > certificate.p12
      - name: Decode provisioning profile
        run: echo '${{ secrets.PROVISIONING_PROFILE }}' | base64 --decode > embedded.mobileprovision
      - name: Build iOS
        run: flutter build ios --release --build-number=${{ github.run_number }} --dart-define=APP_VERSION=${{ github.run_number }}

Step 4: Add Tests

Testing is a crucial part of any CI/CD pipeline. Flutter provides a robust testing framework, and you can easily integrate tests into your GitHub Actions workflow. In the initial workflow file, we already included a step to run flutter test. However, you can customize this step to run specific tests or generate coverage reports.

To add more specific testing steps, you can modify your main.yml file as follows:

- run: flutter test integration_test/app_test.dart

Step 5: Artifact Upload

After building your app, you'll likely want to upload the generated artifacts (e.g., APK, IPA, App Bundle) for distribution or further processing. GitHub Actions provides the actions/upload-artifact action for this purpose.

To upload the generated artifacts, add the following steps to your main.yml file:

- uses: actions/upload-artifact@v3
  with:
    name: android-appbundle
    path: build/app/outputs/bundle/release/app-release.aab

- uses: actions/upload-artifact@v3
  with:
    name: ios-app
    path: build/ios/iphoneos/Runner.app

These steps upload the Android App Bundle and the iOS app as artifacts, which can be downloaded from the GitHub Actions UI.

Step 6: Distribute the App

Deploying the app to a testing service such as Firebase App Distribution or deploying directly to the Google Play Store or Apple App Store Connect can be automated. Here’s how to set it up:

Firebase App Distribution

Set up Firebase Project: Create a Firebase project and enable App Distribution.
Install Firebase CLI: Install the Firebase CLI tools.
Generate a Firebase Token: Generate a Firebase token to authenticate with your Firebase project.
Add Secrets: Add the Firebase token to your GitHub repository secrets as FIREBASE_TOKEN.
Update Workflow File: Add the steps to distribute the app using Firebase App Distribution:

- name: Distribute to Firebase App Distribution
  run: |-
    firebase appdistribution:distribute build/app/outputs/bundle/release/app-release.aab \
      --app <your_firebase_app_id> \
      --token ${{ secrets.FIREBASE_TOKEN }} \
      --release-notes "Release notes for this build."

Google Play Store

Set up Google Play Console: Create a Google Play Console account and set up your app.
Create a Service Account: Create a service account in the Google Cloud Console and grant it the necessary permissions to access your Google Play Console account.
Download the Service Account Key: Download the JSON key file for your service account.
Add Secrets: Add the base64 encoded content of your service account key to your GitHub repository secrets as GOOGLE_PLAY_SERVICE_ACCOUNT_JSON.
Update Workflow File: Add the steps to deploy the app to the Google Play Store using the r0adkll/upload-google-play action:

- uses: r0adkll/upload-google-play@v1
  with:
    serviceAccountJsonPlainText: ${{ secrets.GOOGLE_PLAY_SERVICE_ACCOUNT_JSON }}
    packageName: com.example.yourapp
    releaseFile: build/app/outputs/bundle/release/app-release.aab
    track: internal

Apple App Store Connect

Set up App Store Connect API: Generate an API key in App Store Connect.
Add Secrets: Add the API key details to your GitHub repository secrets.
- APP_STORE_CONNECT_ISSUER_ID: The issuer ID for your App Store Connect API key.
- APP_STORE_CONNECT_KEY_ID: The key ID for your App Store Connect API key.
- APP_STORE_CONNECT_PRIVATE_KEY: The private key for your App Store Connect API key.
Update Workflow File: Add the steps to deploy the app to TestFlight using the apple-actions/upload-testflight-build action:

- uses: apple-actions/upload-testflight-build@v3
  with:
    app_store_connect_api_key_issuer_id: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
    app_store_connect_api_key_id: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
    app_store_connect_api_key: ${{ secrets.APP_STORE_CONNECT_PRIVATE_KEY }}
    path: build/ios/iphoneos/Runner.app

Best Practices for GitHub Actions with Flutter

Keep Workflows Modular: Break down your workflows into smaller, reusable components.
Use Secrets Wisely: Store sensitive information (e.g., API keys, passwords) as GitHub secrets.
Cache Dependencies: Use caching to speed up build times by reusing downloaded dependencies.
Monitor Workflows: Regularly monitor your workflows to identify and address any issues.
Use Specific Versions: Specify the versions of actions to ensure stability and prevent unexpected behavior.

Troubleshooting

Workflow Fails: Check the workflow logs for error messages and address any issues with your code or configuration.
Build Errors: Ensure that your Flutter project is configured correctly and that all dependencies are installed.
Deployment Errors: Verify that your deployment credentials are valid and that you have the necessary permissions.

Conclusion

Automating your Flutter app builds with GitHub Actions can significantly improve your development workflow. By following this guide, you can set up a robust CI/CD pipeline that automates the build, test, and deployment phases, ensuring a smoother and more efficient development process. Embrace the power of automation and take your Flutter development to the next level! This detailed guide should help you set up a solid foundation for automating your Flutter app builds. Remember to adapt the configurations to fit your specific project needs and always keep security in mind when handling sensitive information.