CI/CD Integration Overview

Integrate App Store Connect CLI into your CI/CD pipelines for automated iOS, macOS, tvOS, and visionOS workflows

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:

Install asc using platform-specific actions/components
Authenticate using environment variables
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 }}

include:
  - component: gitlab.com/rudrankriyam/asc-ci-components/run@main
    inputs:
      stage: deploy
      job_prefix: release
      asc_version: latest
      command: asc apps list

workflows:
  primary:
    steps:
    - git::https://github.com/rudrankriyam/steps-setup-asc.git@main:
        inputs:
        - mode: run
        - version: latest
        - command: asc apps list

orbs:
  asc: rudrankriyam/[email protected]

jobs:
  deploy:
    steps:
      - asc/install
      - run: asc apps list

Authentication in CI

Environment Variables

All CI platforms use the same authentication environment variables:

Variable	Description	Required
`ASC_KEY_ID`	App Store Connect API Key ID	Yes
`ASC_ISSUER_ID`	App Store Connect Issuer ID	Yes
`ASC_PRIVATE_KEY_B64`	Base64-encoded private key (`.p8` file)	Yes*
`ASC_PRIVATE_KEY_PATH`	Path to `.p8` file (alternative)	Yes*
`ASC_PRIVATE_KEY`	Raw private key content (alternative)	Yes*

*One of these three private key options is required.

Generating API Keys

Visit App Store Connect API Keys
Create a new API key with appropriate permissions
Download the .p8 private key file (only available once!)
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.

GitHub Actions
GitLab CI
Bitrise
CircleCI

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

Store credentials in Settings > CI/CD > Variables:

ASC_KEY_ID
ASC_ISSUER_ID
ASC_PRIVATE_KEY_B64

Mark as Protected and Masked for security.

Store credentials in Workflow > Secrets:

ASC_KEY_ID
ASC_ISSUER_ID
ASC_PRIVATE_KEY_B64

Enable “Expose for Pull Requests” only if needed.

Store credentials in Project Settings > Environment Variables:

ASC_KEY_ID
ASC_ISSUER_ID
ASC_PRIVATE_KEY_B64

Optional Environment Variables

Customize asc behavior in CI:

Variable	Purpose	Default
`ASC_DEFAULT_OUTPUT`	Output format (`json`, `table`, `markdown`)	`json` in CI
`ASC_TIMEOUT`	Request timeout (e.g., `90s`, `2m`)	`60s`
`ASC_UPLOAD_TIMEOUT`	Upload timeout (e.g., `5m`, `10m`)	`5m`
`ASC_DEBUG`	Enable debug logging (`true`, `api`)	-
`ASC_STRICT_AUTH`	Fail on multiple credential sources	`false`
`ASC_APP_ID`	Default app ID for commands	-

Common CI/CD Workflows

TestFlight Distribution

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

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

App Store Submission

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

# Run the canonical App Store publish command
asc publish appstore \
  --app "123456789" \
  --ipa "./MyApp.ipa" \
  --version "1.2.3" \
  --submit \
  --confirm

Metadata Updates

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

# Upload screenshots
asc screenshots upload \
  --version-localization "VERSION_LOCALIZATION_ID" \
  --device-type "IPHONE_65" \
  --path "screenshot.png"

Crash and Feedback Monitoring

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

# Get feedback
asc testflight feedback list \
  --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" --ipa "$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 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

Use explicit flags

Always use long-form flags (--app, --version) instead of short forms for clarity in CI logs:

# Good
asc builds upload --app "123456789" --ipa "MyApp.ipa"

# Avoid in CI
asc builds upload --app "123456789" --ipa "MyApp.ipa"

Set timeouts

Configure timeouts for long-running operations:

env:
  ASC_TIMEOUT: 2m
  ASC_UPLOAD_TIMEOUT: 10m

Enable debug logging for troubleshooting

Use ASC_DEBUG=api to log HTTP requests/responses:

ASC_DEBUG=api asc builds upload --app "$APP_ID" --ipa "$IPA_PATH"

Handle pagination

Use --paginate to fetch all results automatically:

asc testflight feedback list --app "123456789" --paginate --output json > feedback.json

Validate before destructive operations

Use validation commands before submissions:

asc validate --app "$APP_ID" --version "$VERSION" || exit 1
asc publish appstore --app "$APP_ID" --ipa "./MyApp.ipa" --version "$VERSION" --submit --confirm

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" --ipa "$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

Getting Started

Core Concepts

Guides