Gpc Migrate Fastlane

gpc-migrate-fastlane

Complete guide for migrating from Fastlane supply to GPC.

When to use

• Migrating from Fastlane supply to GPC (partial or full)
• Running GPC alongside Fastlane during a transition period
• Comparing Fastlane and GPC commands
• Converting Fastlane CI workflows to GPC
• Understanding metadata directory compatibility

Inputs required

• Existing Fastlane setup — Fastfile, Appfile, metadata directory
• Service account key — same key file works for both tools
• App package name — from Appfile or Fastfile configuration

Procedure

1. Assess current Fastlane usage

Identify which Fastlane supply features you use:

# Check your Fastfile for supply lanes
cat fastlane/Fastfile | grep -A 10 'supply'

# Check metadata directory
ls fastlane/metadata/android/

# Check Appfile for config
cat fastlane/Appfile

2. Install GPC (keep Fastlane installed)

npm install -g @gpc-cli/cli

Both tools can coexist — they share the same service account keys and metadata directory structure.

3. Authenticate with the same service account

# Use the same key file from Fastlane
gpc auth login --service-account path/to/play-store-key.json

# Or set via environment variable (same as SUPPLY_JSON_KEY)
export GPC_SERVICE_ACCOUNT=$(cat path/to/play-store-key.json)

# Configure default app (from your Appfile)
gpc config set app com.example.app

# Verify
gpc doctor

4. Map your Fastlane commands to GPC

Read: references/command-mapping.md for the complete command mapping table.

Key mappings:

# Upload AAB
# Fastlane: fastlane supply --aab app.aab --track beta
# GPC:
gpc releases upload app.aab --track beta

# Upload with rollout
# Fastlane: fastlane supply --aab app.aab --track production --rollout 0.1
# GPC:      (note: percentage, not decimal)
gpc releases upload app.aab --track production --rollout 10

# Download metadata
# Fastlane: fastlane supply --download_metadata --metadata_path metadata/
# GPC:
gpc listings pull --dir metadata/

# Push metadata
# Fastlane: fastlane supply --skip_upload_aab --metadata_path metadata/
# GPC:
gpc listings push --dir metadata/

# Upload screenshots (one-shot)
# Fastlane: fastlane supply --skip_upload_aab --skip_upload_metadata
# GPC:
gpc listings images upload --lang en-US --type phoneScreenshots *.png

# Sync screenshots from a directory (v0.9.69+ — equivalent to Fastlane's sync_image_upload)
# SHA-256 content hashing: only uploads new/changed files; --delete removes extras remotely.
gpc listings images sync --lang en-US --type phoneScreenshots --dir ./screenshots/en-US/ --delete

# In-app update priority (v0.9.70+ — equivalent to Fastlane's in_app_update_priority)
# Fastlane: supply(in_app_update_priority: 3)
# GPC:
gpc releases upload app.aab --track production --in-app-update-priority 3

# Retain previous version codes (v0.9.70+)
# Fastlane: supply(version_codes_to_retain: [40, 41])
# GPC:
gpc releases upload app.aab --track internal --retain-version-codes 40,41

# Fastlane-style versioned changelogs (v0.9.70+)
# If your changelogs/ directory uses the Fastlane layout:
#   changelogs/en-US/42.txt, changelogs/en-US/default.txt, changelogs/ja-JP/default.txt
# GPC auto-detects the structure. Reads {versionCode}.txt first, falls back to default.txt.
gpc releases upload app.aab --track production --notes-dir changelogs/

5. Test with dry-run

Before switching any CI pipeline, verify GPC produces the same results:

# Preview metadata push (no changes applied)
gpc listings push --dir fastlane/metadata/android/ --dry-run

# Preview upload (validates AAB without uploading)
gpc validate app.aab

# Compare listing output
gpc listings view --lang en-US --json

6. Migrate CI configuration

Read: references/ci-migration.md for platform-specific CI migration examples.

Replace Fastlane supply calls in your CI with GPC equivalents:

# Before (GitHub Actions with Fastlane)
- name: Deploy to beta
  run: bundle exec fastlane supply --aab app.aab --track beta

# After (GitHub Actions with GPC)
- name: Deploy to beta
  env:
    GPC_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_KEY }}
    GPC_APP: com.example.app
  run: npx @gpc-cli/cli releases upload app.aab --track beta

7. Clean up Fastlane (optional)

Once fully migrated and confident:

# Remove Fastlane files
rm -rf fastlane/Fastfile fastlane/Appfile fastlane/Pluginfile
rm Gemfile Gemfile.lock

# Keep metadata directory — GPC uses the same structure
# fastlane/metadata/android/ → works with both tools

Note: The metadata directory (fastlane/metadata/android/) is fully compatible. You can rename it if you want (e.g., metadata/) — just update the --dir flag.

Verification

• gpc doctor passes all checks
• gpc listings push --dir fastlane/metadata/android/ --dry-run shows no errors
• gpc releases upload app.aab --track internal --dry-run validates the bundle
• CI pipeline runs successfully with GPC commands
• Metadata and screenshots match what was uploaded via Fastlane

Failure modes / debugging

Related skills

• gpc-setup — initial authentication and configuration
• gpc-metadata-sync — detailed metadata management beyond migration
• gpc-release-flow — full release lifecycle with GPC
• gpc-ci-integration — CI/CD pipeline setup with GPC

CI Migration: Fastlane → GPC

Platform-specific examples for replacing Fastlane supply with GPC in CI pipelines.

GitHub Actions

Before (Fastlane)

name: Deploy
on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
      - name: Deploy to beta
        env:
          SUPPLY_JSON_KEY_DATA: ${{ secrets.PLAY_SA_KEY }}
        run: bundle exec fastlane supply --aab app.aab --track beta

After (GPC)

name: Deploy
on:
  push:
    tags: ['v*']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Deploy to beta
        env:
          GPC_SERVICE_ACCOUNT: ${{ secrets.PLAY_SA_KEY }}
          GPC_APP: com.example.app
        run: npx @gpc-cli/cli releases upload app.aab --track beta

Key differences:

• No Ruby/Bundler setup needed
• SUPPLY_JSON_KEY_DATA → GPC_SERVICE_ACCOUNT
• bundle exec fastlane supply → npx @gpc-cli/cli releases upload
• Add GPC_APP (Fastlane reads from Appfile)

GitLab CI

Before (Fastlane)

deploy:
  image: ruby:3.2
  stage: deploy
  only: [tags]
  before_script:
    - bundle install
  script:
    - bundle exec fastlane supply --aab app.aab --track beta

After (GPC)

deploy:
  image: node:20
  stage: deploy
  only: [tags]
  variables:
    GPC_SERVICE_ACCOUNT: $PLAY_SA_KEY
    GPC_APP: com.example.app
  script:
    - npx @gpc-cli/cli releases upload app.aab --track beta

Bitbucket Pipelines

Before (Fastlane)

pipelines:
  tags:
    'v*':
      - step:
          image: ruby:3.2
          script:
            - bundle install
            - bundle exec fastlane supply --aab app.aab --track beta

After (GPC)

pipelines:
  tags:
    'v*':
      - step:
          image: node:20
          script:
            - npx @gpc-cli/cli releases upload app.aab --track beta

Secrets migration

The same secret value works — just change the environment variable name.

Added benefits after migration

Once on GPC, you can add these capabilities that Fastlane doesn't have:

# Vitals gating before production promotion
- name: Check vitals
  run: npx @gpc-cli/cli vitals crashes --threshold 1.5

# Staged rollout with percentage control
- name: Promote with rollout
  run: npx @gpc-cli/cli releases promote --from beta --to production --rollout 10

# Step summary in GitHub Actions (via plugin-ci)
- name: Upload with summary
  run: npx @gpc-cli/cli releases upload app.aab --track beta
  # Automatically writes to $GITHUB_STEP_SUMMARY

Fastlane → GPC Command Mapping

Complete mapping of Fastlane supply commands to GPC equivalents.

Uploads and releases

Rollout difference: Fastlane uses decimal (0.0–1.0), GPC uses percentage (0–100).

Metadata

Track promotion

GPC provides granular rollout control that Fastlane doesn't support natively.

Release notes

Release-notes automation (v0.9.62+): Fastlane users manage per-locale metadata/android/<lang>/changelogs/<version>.txt files by hand. GPC v0.9.62+ can generate them from your git log:

gpc changelog generate --target play-store --locales auto --format json --app com.example.app

Pair with --ai (v0.9.63+) for automatic LLM translation and --apply (v0.9.64+) to write translated notes directly into the draft release. End-to-end: gpc changelog generate --target play-store --locales auto --ai --apply.

App information

Environment variables

Features GPC has that Fastlane doesn't