Claude Code × App Store Connect API: A Complete Automated iOS/Android Release Pipeline Guide

# .env.local (keep this out of Git)
APP_STORE_CONNECT_KEY_ID=XXXXXXXXXX
APP_STORE_CONNECT_ISSUER_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
APP_STORE_CONNECT_KEY_PATH=/path/to/AuthKey_XXXXXXXXXX.p8

# Install Fastlane
gem install fastlane
 
# Initialize in your project root
cd /path/to/YourApp
fastlane init

# fastlane/Appfile
app_identifier "com.example.yourapp"
apple_id "developer@example.com"
 
# Use App Store Connect API (recommended over username/password auth)
api_key_path "./fastlane/app_store_connect_api_key.json"

{
  "key_id": "YOUR_KEY_ID",
  "issuer_id": "YOUR_ISSUER_ID",
  "key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
}

## Version Management
 
Version numbers must be kept in sync across these four locations:
1. `ios/YourApp/Info.plist` — CFBundleShortVersionString and CFBundleVersion
2. `android/app/build.gradle` — versionName and versionCode
3. `package.json` — version field (React Native projects)
4. `CHANGELOG.md` — latest entry header
 
When bumping versions, always update all four locations in a single commit.
Use the commit message format: chore: bump version to X.Y.Z (build NNN)
The versionCode / build number must always increment by 1 from the previous value.

claude "Please update the version to 2.3.0 (build 231).
Follow the instructions in CLAUDE.md and update all four locations in one commit."

#!/usr/bin/env python3
# scripts/generate_release_notes.py
 
import subprocess
import json
import os
import anthropic
 
def get_commits_since_last_tag():
    """Retrieve commits since the last release tag."""
    try:
        last_tag = subprocess.check_output(
            ["git", "describe", "--tags", "--abbrev=0", "HEAD^"],
            text=True
        ).strip()
 
        commits = subprocess.check_output(
            ["git", "log", f"{last_tag}..HEAD", "--oneline", "--no-merges"],
            text=True
        ).strip()
 
        return last_tag, commits
    except subprocess.CalledProcessError:
        # Fallback if no previous tags exist
        commits = subprocess.check_output(
            ["git", "log", "--oneline", "--no-merges", "-20"],
            text=True
        ).strip()
        return "v0.0.0", commits
 
def generate_release_notes(commits, version, app_name):
    """Use the Claude API to generate bilingual release notes."""
    client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
 
    prompt = f"""You are writing release notes for the mobile app "{app_name}" (version {version}).
 
Based on the commit history below, write App Store release notes in both Japanese and English.
 
# Commit History
{commits}
 
# Output Format (JSON only, no other text)
{{
  "ja": {{
    "whats_new": "What is new in Japanese (under 200 characters, user-focused, warm tone)"
  }},
  "en": {{
    "whats_new": "What is new in English (under 200 characters, user-focused, warm tone)"
  }}
}}
 
Rules:
- Skip technical commits (chore:, refactor:, ci:, docs:, test:) unless they have user impact
- Focus on user-visible changes and improvements
- Use friendly, accessible language — not developer jargon
- If there are no user-visible changes, write about stability improvements
- Keep each version under 200 characters to fit App Store display limits
"""
 
    message = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=1024,
        messages=[{"role": "user", "content": prompt}]
    )
 
    content = message.content[0].text
    json_start = content.find("{")
    json_end = content.rfind("}") + 1
    return json.loads(content[json_start:json_end])
 
def main():
    app_name = os.environ.get("APP_NAME", "MyApp")
    version = os.environ.get("APP_VERSION", "1.0.0")
 
    last_tag, commits = get_commits_since_last_tag()
    print(f"Last tag: {last_tag}")
    print(f"Commits to summarize: {len(commits.splitlines())}")
 
    release_notes = generate_release_notes(commits, version, app_name)
 
    # Write to Fastlane metadata directories
    ja_dir = "fastlane/metadata/ja"
    en_dir = "fastlane/metadata/en-US"
    os.makedirs(ja_dir, exist_ok=True)
    os.makedirs(en_dir, exist_ok=True)
 
    with open(f"{ja_dir}/release_notes.txt", "w") as f:
        f.write(release_notes["ja"]["whats_new"])
 
    with open(f"{en_dir}/release_notes.txt", "w") as f:
        f.write(release_notes["en"]["whats_new"])
 
    print("Release notes generated successfully")
    print(f"JA: {release_notes['ja']['whats_new']}")
    print(f"EN: {release_notes['en']['whats_new']}")
 
if __name__ == "__main__":
    main()

# fastlane/Snapfile
devices([
  "iPhone 16 Pro Max",
  "iPhone 16",
  "iPhone SE (3rd generation)",
  "iPad Pro 13-inch (M4)"
])
 
languages([
  "ja",
  "en-US"
])
 
scheme "YourAppUITests"
output_directory "./fastlane/screenshots"
clear_previous_screenshots true

// YourAppUITests/SnapshotTests.swift
import XCTest
 
class SnapshotTests: XCTestCase {
 
    func testCaptureScreenshots() throws {
        let app = XCUIApplication()
        setupSnapshot(app)
        app.launch()
 
        // Capture the home screen
        snapshot("01_HomeScreen")
 
        // Navigate to search and capture
        app.tabBars.buttons.matching(identifier: "search").firstMatch.tap()
        snapshot("02_SearchScreen")
 
        // Navigate to settings and capture
        app.tabBars.buttons.matching(identifier: "settings").firstMatch.tap()
        snapshot("03_SettingsScreen")
    }
}

# fastlane/Fastfile
platform :ios do
 
  desc "Build and distribute to TestFlight beta testers"
  lane :beta do
    version = ENV["APP_VERSION"] || get_version_number
    build_num = ENV["BUILD_NUMBER"] || get_build_number
 
    # Build the app for release
    gym(
      scheme: "YourApp",
      configuration: "Release",
      export_method: "app-store",
      output_directory: "./build",
      output_name: "YourApp.ipa"
    )
 
    # Upload to TestFlight
    pilot(
      ipa: "./build/YourApp.ipa",
      skip_waiting_for_build_processing: false,
      distribute_external: true,
      groups: ["Beta Testers"],
      changelog: File.read("fastlane/metadata/en-US/release_notes.txt"),
      notify_external_testers: true
    )
 
    # Notify the team on Slack
    slack(
      message: "TestFlight build #{version} (#{build_num}) is live and ready for review",
      slack_url: ENV["SLACK_WEBHOOK_URL"],
      success: true
    )
  end
 
  desc "Submit to App Store review"
  lane :release do
    # Capture fresh screenshots before submitting
    snapshot
 
    # Upload metadata, screenshots, and submit for review
    deliver(
      submit_for_review: true,
      automatic_release: false,
      force: true,
      metadata_path: "./fastlane/metadata",
      screenshots_path: "./fastlane/screenshots"
    )
 
    puts "Submitted for review. Apple typically responds within 24 to 48 hours."
  end
end

# .github/workflows/release.yml
name: Release Pipeline
 
on:
  push:
    branches:
      - 'release/*'
  workflow_dispatch:
    inputs:
      version:
        description: 'Release version (e.g., 2.3.0)'
        required: true
 
jobs:
  release:
    name: Build and Deploy to TestFlight
    runs-on: macos-15
 
    steps:
      - name: Checkout with full history for release notes
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Set up Ruby and Fastlane
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
 
      - name: Install Python dependencies
        run: pip install anthropic
 
      - name: Extract version from branch name
        id: version
        run: |
          BRANCH="${{ github.ref_name }}"
          VERSION=$(echo "$BRANCH" | sed 's/release\///')
          echo "version=$VERSION" >> $GITHUB_OUTPUT
 
      - name: Generate AI release notes
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          APP_VERSION: ${{ steps.version.outputs.version }}
          APP_NAME: "YourApp"
        run: python scripts/generate_release_notes.py
 
      - name: Import code signing certificates
        uses: apple-actions/import-codesign-certs@v3
        with:
          p12-file-base64: ${{ secrets.IOS_P12_BASE64 }}
          p12-password: ${{ secrets.IOS_P12_PASSWORD }}
 
      - name: Run Fastlane beta lane
        env:
          APP_STORE_CONNECT_KEY_ID: ${{ secrets.APP_STORE_CONNECT_KEY_ID }}
          APP_STORE_CONNECT_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_ISSUER_ID }}
          APP_STORE_CONNECT_KEY_CONTENT: ${{ secrets.APP_STORE_CONNECT_KEY_CONTENT }}
          APP_VERSION: ${{ steps.version.outputs.version }}
          BUILD_NUMBER: ${{ github.run_number }}
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
        run: bundle exec fastlane beta

# fastlane/Fastfile (Android section)
platform :android do
 
  desc "Build and upload to Google Play internal testing"
  lane :beta do
    version = ENV["APP_VERSION"] || android_get_version_name
    build_num = ENV["BUILD_NUMBER"] || android_get_version_code.to_i
 
    # Build a signed release APK or AAB
    gradle(
      task: "bundle",
      build_type: "Release",
      project_dir: "android/"
    )
 
    # Upload to Google Play internal testing track
    supply(
      track: "internal",
      aab: lane_context[SharedValues::GRADLE_AAB_OUTPUT_PATH],
      json_key_data: ENV["GOOGLE_PLAY_JSON_KEY_DATA"],
      skip_upload_metadata: false,
      metadata_path: "./fastlane/metadata/android"
    )
 
    # Notify the team
    slack(
      message: "Google Play internal build #{version} (#{build_num}) uploaded",
      slack_url: ENV["SLACK_WEBHOOK_URL"],
      success: true
    )
  end
end

# Add to generate_release_notes.py
 
def write_android_release_notes(release_notes, version_code):
    """Write release notes to the Android metadata structure."""
    android_ja = f"fastlane/metadata/android/ja-JP/changelogs/{version_code}.txt"
    android_en = f"fastlane/metadata/android/en-US/changelogs/{version_code}.txt"
 
    os.makedirs(os.path.dirname(android_ja), exist_ok=True)
    os.makedirs(os.path.dirname(android_en), exist_ok=True)
 
    with open(android_ja, "w") as f:
        f.write(release_notes["ja"]["whats_new"])
 
    with open(android_en, "w") as f:
        f.write(release_notes["en"]["whats_new"])
 
    print(f"Android release notes written for version code {version_code}")

# fastlane/Fastfile (multi-environment)
platform :ios do
 
  # Shared configuration applied to all lanes
  before_all do |lane|
    # Ensure the workspace is clean before building
    ensure_git_status_clean unless lane == :fix
  end
 
  desc "Internal development build"
  lane :internal do
    gym(scheme: "YourApp-Dev", configuration: "Debug", export_method: "development")
    pilot(distribute_external: false, groups: ["Internal Team"])
  end
 
  desc "Beta distribution to external testers"
  lane :beta do
    gym(scheme: "YourApp", configuration: "Release", export_method: "app-store")
    pilot(
      distribute_external: true,
      groups: ["Beta Testers"],
      changelog: File.read("fastlane/metadata/en-US/release_notes.txt")
    )
    slack(message: "Beta build ready for external testers", slack_url: ENV["SLACK_WEBHOOK_URL"])
  end
 
  desc "Production release with phased rollout"
  lane :production do
    # Run screenshot capture before production release
    snapshot
 
    # Deliver with phased release (10% rollout initially)
    deliver(
      submit_for_review: true,
      phased_release: true,
      automatic_release: false
    )
  end
end

def generate_structured_release_notes(commits, version, app_name):
    """Generate release notes with explicit feature/fix sections."""
    client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
 
    prompt = f"""Write App Store release notes for "{app_name}" version {version}.
 
Commits since last release:
{commits}
 
Output JSON with this structure:
{{
  "ja": {{
    "summary": "One sentence summary in Japanese (under 100 chars)",
    "new_features": ["Feature 1 in Japanese", "Feature 2"],
    "improvements": ["Improvement 1", "Improvement 2"],
    "bug_fixes": ["Fix 1", "Fix 2"]
  }},
  "en": {{
    "summary": "One sentence summary in English (under 100 chars)",
    "new_features": ["Feature 1", "Feature 2"],
    "improvements": ["Improvement 1", "Improvement 2"],
    "bug_fixes": ["Fix 1", "Fix 2"]
  }}
}}
 
Only include sections that have actual changes.
Skip sections with no relevant commits.
Use user-friendly language, not commit message syntax.
"""
 
    message = client.messages.create(
        model="claude-opus-4-6",
        max_tokens=2048,
        messages=[{"role": "user", "content": prompt}]
    )
 
    content = message.content[0].text
    json_start = content.find("{")
    json_end = content.rfind("}") + 1
    return json.loads(content[json_start:json_end])
 
def format_structured_notes(notes_data, locale="en"):
    """Format structured notes into App Store-compatible text."""
    parts = []
    data = notes_data[locale]
 
    if data.get("summary"):
        parts.append(data["summary"])
        parts.append("")
 
    if data.get("new_features"):
        parts.append("What's New:" if locale == "en" else "新機能:")
        for feature in data["new_features"]:
            parts.append(f"- {feature}")
        parts.append("")
 
    if data.get("improvements"):
        parts.append("Improvements:" if locale == "en" else "改善:")
        for item in data["improvements"]:
            parts.append(f"- {item}")
        parts.append("")
 
    if data.get("bug_fixes"):
        parts.append("Bug Fixes:" if locale == "en" else "バグ修正:")
        for fix in data["bug_fixes"]:
            parts.append(f"- {fix}")
 
    return "\n".join(parts).strip()

# Normalize newlines when reading key content from environment variables
key_content = os.environ["APP_STORE_CONNECT_KEY_CONTENT"].replace("\\n", "\n")

# Add to .github/workflows/release.yml after the Fastlane step
- name: Tag the release commit on success
  if: success()
  run: |
    git tag "v${{ steps.version.outputs.version }}-build-${{ github.run_number }}"
    git push origin "v${{ steps.version.outputs.version }}-build-${{ github.run_number }}"

#!/usr/bin/env python3
# scripts/validate_release.py
 
import os
import re
import sys
 
def check_release_notes_length():
    """Verify release notes are within App Store limits."""
    for locale, path in [("ja", "fastlane/metadata/ja/release_notes.txt"),
                          ("en-US", "fastlane/metadata/en-US/release_notes.txt")]:
        if not os.path.exists(path):
            print(f"FAIL: Missing release notes for {locale}")
            return False
        with open(path) as f:
            content = f.read()
        if len(content) > 4000:
            print(f"FAIL: {locale} release notes exceed 4000 characters ({len(content)} chars)")
            return False
        if len(content) < 10:
            print(f"FAIL: {locale} release notes appear empty")
            return False
    return True
 
def check_version_consistency():
    """Check that iOS and Android version numbers match."""
    version = os.environ.get("APP_VERSION", "")
    if not re.match(r'^\d+\.\d+\.\d+$', version):
        print(f"FAIL: APP_VERSION '{version}' does not match X.Y.Z format")
        return False
    return True
 
def main():
    checks = [
        ("Release notes length", check_release_notes_length),
        ("Version format", check_version_consistency),
    ]
 
    failed = []
    for name, check in checks:
        if check():
            print(f"PASS: {name}")
        else:
            failed.append(name)
 
    if failed:
        print(f"\nValidation failed: {', '.join(failed)}")
        sys.exit(1)
    else:
        print("\nAll pre-release checks passed.")
 
if __name__ == "__main__":
    main()

deliver(
  submit_for_review: true,
  phased_release: true,  # Enables staged rollout (7% → 100% over 7 days)
  automatic_release: false  # Keep manual release control
)