CI/GitHub Actions Debugging Skill

Expert guidance for debugging GitHub Actions workflows, CI build failures, and deployment issues specific to this Flutter Android project.

When to Use This Skill

• •GitHub Actions workflow failures
• •CI build errors that don't occur locally
• •Test failures only in CI environment
• •Artifact upload/download issues
• •Secret/credential problems
• •Cache-related failures
• •Timeout issues
• •Deployment failures

Project Workflows

This project has several workflows:

1. build.yml (Main CI)

• •Runs on push to main/develop and PRs
• •Auto-formats code with dart format
• •Applies fixes with dart fix --apply
• •Builds APK and App Bundle
• •Runs tests with coverage
• •Uses CI-optimized Gradle properties

2. release.yml

• •Triggered by version tags (v*)
• •Builds signed release artifacts
• •Creates GitHub Release
• •Requires signing secrets

3. pre-release.yml

• •Manual workflow for beta/alpha releases
• •Customizable version naming
• •Creates pre-release on GitHub

Debugging Workflow

1. Access Workflow Logs

Via GitHub UI:

1. •Go to repository → Actions tab
2. •Click on failed workflow run
3. •Click on failed job
4. •Expand failed step to see logs

Via GitHub CLI (if available):

# List recent workflow runs
gh run list --limit 10

# View specific run
gh run view <run-id>

# Download logs
gh run download <run-id>

2. Common CI Failure Patterns

Flutter/Dart Setup Issues

Error: Flutter not found or wrong version

# Check flutter version in workflow
- name: Setup Flutter
  uses: subosito/flutter-action@v2
  with:
    flutter-version: '3.38.3'  # Verify this matches requirements
    channel: 'stable'
    cache: true

Solution:

• •Update Flutter version in .github/workflows/build.yml
• •Ensure version exists on stable channel
• •Check for typos in version number

Gradle Build Failures

Error: Gradle daemon issues or out of memory

# Workflow uses CI-optimized properties
- name: Setup Gradle for CI
  run: cp android/gradle-ci.properties android/gradle.properties

Solution:

• •Check android/gradle-ci.properties settings
• •Verify heap size (3GB for CI)
• •Ensure parallel builds limited (2 workers for CI)
• •Disable daemon in CI: org.gradle.daemon=false

Error: Java version mismatch

- name: Setup Java
  uses: actions/setup-java@v5
  with:
    distribution: 'temurin'
    java-version: '17'  # Must be 17 for this project

Solution:

• •Verify Java version is 17
• •Check all gradle files use Java 17
• •Ensure JVM target is set correctly

Dependency Issues

Error: Package resolution failures

- name: Get dependencies
  run: flutter pub get

Solution:

• •Check pubspec.yaml for invalid dependencies
• •Verify dependency versions exist on pub.dev
• •Clear cache if stale (remove cache step temporarily)
• •Check for network issues in CI environment

Test Failures

Error: Tests pass locally but fail in CI

- name: Run tests with coverage
  run: flutter test --coverage --concurrency=$(nproc)

Solution:

• •Check for timing issues (use await properly)
• •Verify file paths are relative, not absolute
• •Look for environment-specific dependencies
• •Check test runs with same concurrency locally
• •Review timezone/locale differences
• •Ensure no tests depend on external services

Cache Issues

Error: Build slower or cache not working

- name: Cache Flutter packages
  uses: actions/cache@v4
  with:
    path: |
      ~/.pub-cache
      ${{ github.workspace }}/.dart_tool
    key: ${{ runner.os }}-pub-${{ hashFiles('**/pubspec.lock') }}

Solution:

• •Verify cache key is correct
• •Check cache paths exist
• •Clear cache by changing cache key
• •Review cache size limits (10GB per repo)

Artifact Upload Issues

Error: Artifacts not found or upload fails

- name: Upload APK
  uses: actions/upload-artifact@v5
  with:
    name: android-apk
    path: build/app/outputs/flutter-apk/app-release.apk
    retention-days: 7

Solution:

• •Verify build actually succeeded
• •Check file path is correct
• •Ensure build step completed
• •Look for build output location changes

3. Debugging Specific Workflow Steps

Auto-format and Commit Step

Error: Permission denied or merge conflicts

- name: Commit formatting changes
  if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
  run: |
    git config user.name "github-actions[bot]"
    git config user.email "github-actions[bot]@users.noreply.github.com"
    git add .
    if git diff --staged --quiet; then
      echo "No formatting changes to commit"
    else
      git commit -m "style: auto-format code [skip ci]"
      git push
    fi

Solution:

• •Check GITHUB_TOKEN has write permissions
• •Verify checkout uses correct ref
• •Ensure condition matches PR from same repo
• •Review branch protection rules

Coverage Upload

Error: Codecov upload fails

- name: Upload Coverage
  uses: codecov/codecov-action@v5
  if: always()
  with:
    files: coverage/lcov.info
    fail_ci_if_error: false
    token: ${{ secrets.CODECOV_TOKEN }}

Solution:

• •Check coverage/lcov.info exists
• •Verify CODECOV_TOKEN secret is set
• •Use fail_ci_if_error: false to not block CI
• •Check Codecov service status

4. Release Workflow Issues

Missing Secrets

Error: Build signing fails

# Required secrets for release.yml:
# - ANDROID_KEYSTORE_BASE64
# - ANDROID_KEYSTORE_PASSWORD
# - ANDROID_KEY_ALIAS
# - ANDROID_KEY_PASSWORD

Solution:

1. •Generate keystore (see SIGNING.md)
2. •Base64 encode: base64 -i keystore.jks -o keystore.txt
3. •Add secrets in Settings → Secrets → Actions
4. •Verify secret names match workflow

Tag Trigger Issues

Error: Release workflow doesn't trigger

on:
  push:
    tags:
      - 'v*'  # Must start with 'v'

Solution:

• •Ensure tag starts with 'v' (e.g., v1.0.0)
• •Push tag: git tag v1.0.0 && git push origin v1.0.0
• •Check workflow is enabled
• •Verify branch has tag

5. Timeout Issues

Error: Workflow times out

jobs:
  build:
    runs-on: ubuntu-latest
    timeout-minutes: 30  # build.yml timeout

Solution:

• •Increase timeout if builds legitimately take longer
• •Check for hanging processes
• •Review Gradle performance settings
• •Ensure no infinite loops in tests
• •Check for network timeouts

6. Concurrency Issues

Error: Multiple runs conflict

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

Solution:

• •This cancels duplicate runs automatically
• •If issues persist, check for race conditions
• •Review if multiple workflows modify same files

Quick CI Debug Checklist

• • Check workflow logs in GitHub Actions tab
• • Verify Flutter version matches project requirements
• • Confirm Java version is 17
• • Review gradle-ci.properties settings
• • Check all required secrets are set
• • Verify dependency versions in pubspec.yaml
• • Test same commands locally
• • Review cache configuration
• • Check artifact paths
• • Verify branch protection rules allow bot commits
• • Ensure workflows are enabled
• • Check runner OS matches expectations (ubuntu-latest)

Local CI Simulation

To reproduce CI environment locally:

# Use CI Gradle properties
cp android/gradle-ci.properties android/gradle.properties

# Clean build
flutter clean
flutter pub get

# Format and fix
dart format .
dart fix --apply

# Analyze
flutter analyze

# Test with coverage
flutter test --coverage --concurrency=$(nproc)

# Build
flutter build apk --release
flutter build appbundle --release

# Restore local properties
git checkout android/gradle.properties

Common Error Messages and Solutions

Best Practices

1. •Always test locally first: Run same commands as CI
2. •Use verbose logging: Add --verbose to debug commands
3. •Check all secrets: Verify secrets exist and are correct
4. •Monitor cache usage: Clear cache if builds become inconsistent
5. •Keep workflows simple: Complex workflows are harder to debug
6. •Use conditional steps: if: always() for critical diagnostics
7. •Set appropriate timeouts: Balance between too short and too long
8. •Document workflow changes: Add comments explaining why
9. •Test on clean branch: Ensure no local state affects CI
10. •Review workflow on successful runs: Understand what works

Additional Resources

• •GitHub Actions Documentation
• •Flutter CI/CD Guide
• •Gradle Build Performance
• •Project-specific: BUILD_OPTIMIZATION.md, SIGNING.md