# Configuring Github Actions

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

- Skill: `poorgramer-zack/configuring-github-actions` (Agent Skill)
- Install (CLI): `npx skillmds@latest add poorgramer-zack/configuring-github-actions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poorgramer-zack/configuring-github-actions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Poorgramer-Zack (https://skillmd.com/u/poorgramer-zack)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/poorgramer-zack/configuring-github-actions

---


# 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](https://github.com/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`.

```yaml
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.

```yaml
      - 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.

```yaml
      # 🌟 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.

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