Skip to main content

​
Introduction

The App Store Connect CLI (asc) is designed for seamless integration into CI/CD pipelines. Whether you’re using GitHub Actions, GitLab CI, Bitrise, or CircleCI, asc provides:
  • Fast, scriptable automation for App Store Connect workflows
  • No interactive prompts - all operations use explicit flags
  • TTY-aware output - automatic JSON output in CI environments
  • Built-in timeout controls for reliable pipeline execution
  • Secure credential management via environment variables

​
Quick Start

All CI platforms follow the same basic pattern:
  1. Install asc using platform-specific actions/components
  2. Authenticate using environment variables
  3. Run commands with explicit flags
- uses: rudrankriyam/setup-asc@v1
  with:
    version: latest

- run: asc apps list
  env:
    ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
    ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
    ASC_PRIVATE_KEY_B64: ${{ secrets.ASC_PRIVATE_KEY_B64 }}

​
Authentication in CI

​
Environment Variables

All CI platforms use the same authentication environment variables:
VariableDescriptionRequired
ASC_KEY_IDApp Store Connect API Key IDYes
ASC_ISSUER_IDApp Store Connect Issuer IDYes
ASC_PRIVATE_KEY_B64Base64-encoded private key (.p8 file)Yes*
ASC_PRIVATE_KEY_PATHPath to .p8 file (alternative)Yes*
ASC_PRIVATE_KEYRaw private key content (alternative)Yes*
*One of these three private key options is required.

​
Generating API Keys

  1. Visit App Store Connect API Keys
  2. Create a new API key with appropriate permissions
  3. Download the .p8 private key file (only available once!)
  4. Note the Key ID and Issuer ID

​
Storing Credentials

Never commit API keys or private keys to version control. Always use your CI platform’s secret management.
Store credentials in Settings > Secrets and variables > Actions:
  • ASC_KEY_ID
  • ASC_ISSUER_ID
  • ASC_PRIVATE_KEY_B64
Base64-encode your private key:
base64 -i AuthKey_ABC123.p8 | pbcopy

​
Optional Environment Variables

Customize asc behavior in CI:
VariablePurposeDefault
ASC_DEFAULT_OUTPUTOutput format (json, table, markdown)json in CI
ASC_TIMEOUTRequest timeout (e.g., 90s, 2m)60s
ASC_UPLOAD_TIMEOUTUpload timeout (e.g., 5m, 10m)5m
ASC_DEBUGEnable debug logging (true, api)-
ASC_STRICT_AUTHFail on multiple credential sourcesfalse
ASC_APP_IDDefault app ID for commands-

​
Common CI/CD Workflows

​
TestFlight Distribution

# Upload build to TestFlight
asc builds upload \
  --app "123456789" \
  --file "/path/to/MyApp.ipa"

# Add to beta group
asc testflight builds add-to-group \
  --build "BUILD_ID" \
  --group "External Testers"

​
App Store Submission

# Validate version
asc validate \
  --app "123456789" \
  --version "1.2.3"

# Submit for review
asc submit \
  --app "123456789" \
  --version "1.2.3"

​
Metadata Updates

# Update app description
asc app-info update \
  --app "123456789" \
  --description "New description" \
  --locale en-US

# Upload screenshots
asc screenshots upload \
  --app "123456789" \
  --version "1.2.3" \
  --locale en-US \
  --display-type APP_IPHONE_67 \
  --file "screenshot.png"

​
Crash and Feedback Monitoring

# Get latest crashes
asc crashes \
  --app "123456789" \
  --sort -createdDate \
  --limit 10 \
  --output json

# Get feedback
asc feedback \
  --app "123456789" \
  --paginate

​
Exit Codes

asc uses standard exit codes for reliable CI integration:
  • 0 - Success
  • 1 - Runtime error (API failures, network issues, etc.)
  • 2 - Usage error (invalid flags, missing arguments, etc.)
Example error handling: 
if ! asc builds upload --app "$APP_ID" --file "$IPA_PATH"; then
  echo "Build upload failed"
  exit 1
fi

​
Output Formats

​
Automatic JSON in CI

When running in non-interactive environments (CI pipelines), asc automatically outputs JSON: 
# Outputs JSON in CI, table in terminal
asc apps list

​
Explicit Output Control

# Force JSON output
asc apps list --output json

# Pretty-printed JSON
asc apps list --output json --pretty

# Markdown tables
asc apps list --output markdown

​
Parsing JSON Output

# Using jq to extract app IDs
APP_ID=$(asc apps list --output json | jq -r '.[0].id')

# Get build status
STATUS=$(asc testflight builds list --app "$APP_ID" --output json | jq -r '.[0].processingState')

​
Platform-Specific Guides

Detailed integration guides for each platform:

GitHub Actions

Official action with version caching and matrix builds

GitLab CI

Reusable components for install and run workflows

Bitrise

Step-based integration with environment variable support

CircleCI

Official orb for CircleCI pipelines

​
Best Practices

Always use long-form flags (--app, --version) instead of short forms for clarity in CI logs:
# Good
asc builds upload --app "123456789" --file "MyApp.ipa"

# Avoid in CI
asc builds upload -a "123456789" -f "MyApp.ipa"
Configure timeouts for long-running operations:
env:
  ASC_TIMEOUT: 2m
  ASC_UPLOAD_TIMEOUT: 10m
Use ASC_DEBUG=api to log HTTP requests/responses:
ASC_DEBUG=api asc builds upload --app "$APP_ID" --file "$IPA_PATH"
Use --paginate to fetch all results automatically:
asc feedback --app "123456789" --paginate --output json > feedback.json
Use validation commands before submissions:
asc validate --app "$APP_ID" --version "$VERSION" || exit 1
asc submit --app "$APP_ID" --version "$VERSION"

​
Troubleshooting

​
Authentication Failures

# Verify credentials are set
echo "Key ID: ${ASC_KEY_ID:0:8}..."
echo "Issuer ID: ${ASC_ISSUER_ID:0:8}..."
echo "Private Key: ${ASC_PRIVATE_KEY_B64:0:20}..."

# Test authentication
asc apps list --output json

​
Timeout Issues

# Increase timeouts
export ASC_TIMEOUT=5m
export ASC_UPLOAD_TIMEOUT=15m

​
Rate Limiting

App Store Connect API has rate limits. Implement retry logic: 
for i in {1..3}; do
  asc builds upload --app "$APP_ID" --file "$IPA_PATH" && break
  echo "Retry $i/3..."
  sleep 10
done

​
Next Steps

  • Choose your CI platform and follow the specific guide
  • Review the Commands Reference for available operations
  • Check out Authentication for detailed credential management
  • Explore Workflows for advanced automation patterns