Flutter combined with GitHub Actions Best Practices (CI/CD)

Goal

Implements robust CI/CD pipelines using GitHub Actions for Flutter projects. GitHub Actions is the most popular CI/CD platform for open-source and small-to-medium projects. By configuring YAML files under .github/workflows/, you can achieve high automation.

Instructions

1. Environment Setup & Core Setup

In all Flutter Workflows, the core package to use is the third-party maintained subosito/flutter-action.

Best Practices:

1. Bind the Flutter Version: Never use channel: stable or let it automatically fetch the latest version. Explicitly specify flutter-version or use flutter-version-file: pubspec.yaml to guarantee the CI environment exactly matches the local development environment.
2. Enable Cache: flutter pub get is a time-consuming step. Always enable cache: true.

name: Flutter CI

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

jobs:
  build_and_test:
    runs-on: ubuntu-latest # If not building iOS, Ubuntu is the fastest and cheapest
    
    steps:
      - name: 📦 Checkout repository
        uses: actions/checkout@v4

      - name: 🐦 Setup Flutter (Standard or FVM)
        uses: subosito/flutter-action@v2
        with:
          # 🌟 Standard Best Practice: Read from pubspec.yaml
          # flutter-version-file: pubspec.yaml 
          
          # 🌟 FVM Best Practice: If your team uses FVM, read directly from the FVM config!
          flutter-version-file: .fvmrc # Or .fvm/fvm_config.json for older FVM versions
          
          cache: true # 🌟 Enable pub-cache to significantly speed up subsequent builds
          
      # [Optional] If your strict project requirements dictate that all commands MUST be executed via `fvm flutter ...` instead of natively, you must activate the FVM CLI globally:
      # - name: 🛠️ Install FVM CLI
      #   run: dart pub global activate fvm
          
      - name: ⬇️ Get packages
        # If FVM CLI is installed, this becomes: `fvm flutter pub get`
        run: flutter pub get

2. Code Generation

If the project uses packages relying on build_runner (like Freezed, Riverpod, go_router builder), you must execute code generation before testing or compiling.

Best Practice: If it is a Pull Request check, use build_runner build --delete-conflicting-outputs to ensure a clean generation state.

      - name: ⚙️ Run build_runner
        run: dart run build_runner build --delete-conflicting-outputs

3. Analyze & Test

This is the core defense line of CI (Continuous Integration), and it's recommended to strictly require passing these for every PR.

      # 🌟 Check if code formatting follows Dart guidelines (trailing commas, indentation)
      - name: 🔎 Analyze Formatting
        run: dart format --output=none --set-exit-if-changed .

      # 🌟 Run static analysis to ensure no warnings or lint errors
      - name: 🚨 Analyze Code
        run: flutter analyze --no-fatal-warnings

      # 🌟 Run Unit and Widget Tests (If there are integration tests, set up another job with emulators)
      - name: 🧪 Run Tests
        run: flutter test --coverage

4. Build Bundle (Android Example)

If setting up a CD (Continuous Deployment) pipeline, you can automatically build an AAB after tests pass.

      - name: 🔨 Build Android App Bundle (AAB)
        run: flutter build appbundle --release
        
      # Upload the built file to GitHub Actions Artifacts for manual download
      - name: 📤 Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: release-aab
          path: build/app/outputs/bundle/release/app-release.aab

5. Deployment and Key Management (Keystore & App Store)

The downside of GitHub Actions is that it isn't great at handling native certificates.

• Android: You need to convert the keystore into a Base64 string, store it in GitHub Secrets, and use a script in the Workflow to convert it back to a file.
• iOS: More complicated, requiring the handling of Certificates and Provisioning Profiles.

Constraints

• GitHub Actions should primarily be used for CI: In the Flutter ecosystem, GitHub Actions is typically only used for CI (Analyze, Test, Build_runner) to ensure code quality.
• Delegate specific deployments to specialized tools: For actual building and deployment (pushing to App Store/Play Console), delegate to tools optimized for mobile development, like Fastlane or Codemagic (which natively supports Flutter).