Debug Pipelines

Debug pipelines help you understand your build environment, check tool versions, inspect directory structures, and validate configurations. This recipe demonstrates common debugging techniques.

Complete YAML

name: Debug Pipeline
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push
  - pull_request

steps:
  - name: Print environment
    run: env

  - name: Print working directory
    run: pwd

  - name: List files
    run: ls -la

Environment Inspection

name: Environment Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Show all environment variables
    run: env | sort

  - name: Check PATH
    run: echo $PATH

  - name: Check HOME directory
    run: |
      echo "HOME: $HOME"
      ls -la $HOME

  - name: Check Ruby installation
    run: |
      echo "Ruby version:"
      ruby --version
      echo "Gems path:"
      gem env

Tool Version Checking

name: Tool Versions
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Xcode version
    run: |
      xcode-select -p
      xcodebuild -version

  - name: Swift version
    run: swift --version

  - name: Ruby and Fastlane
    run: |
      ruby --version
      gem list | grep fastlane

  - name: CocoaPods
    run: |
      pod --version
      pod repo list

  - name: Git
    run: |
      git --version
      git config user.name
      git config user.email

For Flutter projects, check the Flutter and Dart versions:

  - name: Flutter and Dart versions
    run: |
      fvm flutter --version
      fvm dart --version

Repository State Inspection

name: Repository Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Current directory
    run: pwd

  - name: List root files
    run: ls -la

  - name: Show git status
    run: |
      git status
      git log --oneline -5

  - name: Check cloned repo structure
    run: |
      find . -name "*.xcworkspace" -o -name "Podfile" -o -name "Gemfile" | head -20

  - name: Show branch info
    run: |
      git branch -a
      git rev-parse --abbrev-ref HEAD

Dependency Debugging

name: Dependencies Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Install and check gems
    run: |
      bundle install --verbose
      bundle list

  - name: Install and check pods
    run: |
      pod install --verbose
      pod list --installed

  - name: Check npm packages
    run: |
      npm install
      npm list --depth=0

Xcode Configuration Debugging

name: Xcode Config Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: List Xcode versions
    run: |
      ls -la /Applications/ | grep Xcode
      xcode-select -p

  - name: Show xcworkspace structure
    run: |
      find . -name "*.xcworkspace" -type d
      ls -la MyApp.xcworkspace/

  - name: Dump build settings
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -scheme MyApp \
      -showBuildSettings | head -50

  - name: List available schemes
    run: |
      xcodebuild \
      -workspace MyApp.xcworkspace \
      -list

Network and File System Debugging

name: System Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Check disk space
    run: |
      df -h
      du -sh .

  - name: Check network connectivity
    run: |
      ping -c 2 8.8.8.8
      curl -I https://www.apple.com

  - name: Simulate network issues
    run: |
      networksetup -listallnetworkservices
      nslookup github.com

  - name: Check file permissions
    run: |
      ls -la .runnerhub/
      ls -la ~/.ssh/ || echo "No SSH directory"

Step Isolation Debug

name: Step Isolation Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Step 1 - Set variable
    run: |
      export MY_VAR="hello"
      echo "MY_VAR in step 1: $MY_VAR"

  - name: Step 2 - Check variable
    run: |
      echo "MY_VAR in step 2: ${MY_VAR:-not set}"
      # Variables don't persist between steps

  - name: Step 3 - Create file
    run: |
      echo "data" > /tmp/debug.txt
      cat /tmp/debug.txt

  - name: Step 4 - Read file
    run: |
      cat /tmp/debug.txt  # Files in /tmp persist

Quick Debugging Command

For a minimal debug pipeline:

name: Quick Debug
platform: ios
environment:
  xcode: "16.4"

triggers:
  - push

steps:
  - name: Debug info
    run: |
      echo "=== System Info ==="
      uname -a

      echo "=== Directory ==="
      pwd
      ls -la

      echo "=== Git ==="
      git status

      echo "=== Tools ==="
      xcodebuild -version
      ruby --version
      pod --version

Key Points

Environment Inspection: Use env and echo $VARIABLE to check what’s available
Version Checking: Verify tools are installed and have correct versions
File System: Explore directory structures, check file permissions
Git Info: Verify correct branch, commits, and repository state
Step Isolation: Variables set in one step don’t persist to the next; use files for persistence

Debugging Checklist

When builds fail, check:

Working directory: Verify you’re in the right folder (pwd)
File existence: Confirm Podfile, Gemfile, and schemes exist (ls)
Tool versions: Ensure Xcode, Ruby, and CocoaPods are the expected versions
Git state: Check branch, commit, and any uncommitted changes
Permissions: Verify read/write permissions on required files
Network: Test connectivity to GitHub, CocoaPods repo, and Apple servers
Disk space: Ensure sufficient disk space for build artifacts