name: "configuring-github-actions" description: "Configures GitHub Actions CI/CD workflows for Flutter projects. Use when creating or editing .github/workflows/ YAML files for Flutter, integrating subosito/flutter-action, automating flutter test, flutter analyze, or dart format on push or pull_request events, running build_runner in CI, building Android AAB or iOS IPA artifacts, managing keystore or signing secrets in GitHub Secrets, or combining GitHub Actions with Fastlane or Codemagic for the deployment stage." metadata: last_modified: "2026-04-01 14:35:00 (GMT+8)"

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).