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

Error Message	Likely Cause	Solution
"Flutter SDK not found"	Setup issue	Check flutter-action version and config
"Gradle build failed"	Memory/config	Review gradle-ci.properties
"Test failed"	Environment diff	Check for timing issues, paths
"Permission denied"	Token permissions	Add write permission to workflow
"Artifact not found"	Build didn't complete	Check build step succeeded
"Secret not found"	Missing secret	Add in repository settings
"Timeout"	Takes too long	Increase timeout or optimize build
"Cache restore failed"	Key mismatch	Update cache key

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