Shopify CLI Production Deployment: AI-Optimized Technical Reference

Critical Failure Points

Primary Deploy Failure Causes

• Dev-to-prod transition: shopify app dev cannot be used for production deployment
• TOML configuration errors: Mismatched application_url causes authentication loops (6+ hour debugging time)
• Token expiry: CLI tokens expire every 60-90 days without warning, typically during critical deployments
• Missing --force flag: Causes 10-minute hangs in CI/CD waiting for interactive confirmation

Configuration Requirements

TOML File Structure (Production)

# shopify.app.prod.toml
name = "your-app"
client_id = "your_client_id"
application_url = "https://your-actual-domain.com"  # MUST match deployment URL exactly

[build]
  automatically_update_urls_on_dev = false  # CRITICAL for production

[app_proxy]
  url = "https://your-actual-domain.com/api/proxy"

Critical Warning: application_url must match deployment domain exactly. Mismatches cause authentication loops.

Required Environment Variables

SHOPIFY_CLI_PARTNERS_TOKEN="shpca_abcd1234..."  # Expires 60-90 days
SHOPIFY_APP_URL="https://your-actual-domain.com"
DATABASE_URL="postgresql://user:pass@host:5432/db"  # SQLite resets on deploy
SESSION_SECRET="super-long-random-string-minimum-32-chars"

Database Persistence Reality

Database Type	Cost	Data Persistence	Concurrent Users	Production Viability
SQLite	Free	❌ Wipes on deploy	Single user	Development only
Render PostgreSQL	$7/month	✅ Persistent	Unlimited	Production ready
Supabase	Free tier	✅ Persistent	Good performance	Production ready

Critical: SQLite files are deleted on every container deployment. Use PostgreSQL for production.

Production-Ready GitHub Actions Configuration

name: Deploy to Production
on:
  push:
    branches: [main]
  workflow_dispatch:

env:
  NODE_VERSION: 20

jobs:
  deploy:
    name: Deploy App
    runs-on: ubuntu-latest
    environment: production  # Enables approval gates
    timeout-minutes: 15      # Prevents infinite hangs

    steps:
    - name: Checkout
      uses: actions/checkout@v4

    - name: Setup Node.js
      uses: actions/setup-node@v4
      with:
        node-version: ${{ env.NODE_VERSION }}
        cache: 'npm'

    - name: Install dependencies
      run: npm ci --ignore-scripts

    - name: Install Shopify CLI
      run: npm install -g @shopify/cli@3.84.1

    - name: Deploy with retry logic
      env:
        SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}
        SHOPIFY_APP_URL: ${{ secrets.SHOPIFY_APP_URL }}
      run: |
        for attempt in 1 2 3; do
          if shopify app deploy --config=production --force --verbose; then
            echo "✅ Deployment successful on attempt $attempt"
            exit 0
          else
            echo "❌ Attempt $attempt failed, retrying in 30 seconds..."
            sleep 30
          fi
        done
        echo "💥 All deployment attempts failed"
        exit 1

Required GitHub Secrets

• SHOPIFY_CLI_PARTNERS_TOKEN: Generated in Partner Dashboard, expires without warning
• SHOPIFY_APP_URL: Must match TOML configuration exactly
• DATABASE_URL: PostgreSQL connection string
• SESSION_SECRET: Minimum 32 characters

Environment Protection Setup

Location: GitHub Settings > Environments > production

• Required reviewers: Minimum 1 team member for 3am emergencies
• Wait timer: 10 minutes (catches obvious errors)
• Branch protection: Only allow deployments from main

Common Production Failures and Solutions

Authentication Failures

Error: Authentication failed

• Cause: Token expired (60-90 day lifecycle)
• Solution: Generate new token in Partner Dashboard > Settings > CLI Tokens
• Prevention: Monitor token age, maximum 2 active tokens per account

App Configuration Errors

Error: App not found

• Cause: Wrong client_id in TOML or token for wrong organization
• Solution: Verify dev/prod apps are separate in Partner Dashboard

Error: Invalid configuration

• Cause: application_url mismatch between TOML and actual deployment
• Solution: Update TOML to match exact deployment URL

Deployment Hangs

Error: Command hangs for 10+ minutes

• Cause: Missing --force flag, waiting for interactive confirmation
• Solution: Always use shopify app deploy --config=production --force
• Prevention: Set timeout-minutes: 15 in GitHub Actions

Database Issues

Error: Data disappears after deployment

• Cause: Using SQLite in ephemeral containers
• Solution: Migrate to PostgreSQL with persistent storage
• Cost: Render PostgreSQL $7/month vs free SQLite

Emergency Rollback Process

No CLI rollback command exists

Manual Rollback Steps

1. Navigate to Partner Dashboard > Apps > [Your App] > App versions
2. Click "Make current" on last working version
3. Wait 2-5 minutes for global propagation
4. Fix issue locally and redeploy

Critical: This only rolls back Shopify configuration. Hosting platform (Render/Heroku) requires separate git-based rollback.

Rollback Preparation

- name: Tag release
  run: git tag "release-$(date +%Y%m%d-%H%M%S)"

Resource Requirements

Time Investment

• Initial setup: 4-6 hours including trial-and-error
• Failed deployment debugging: 2-6 hours per incident
• Token expiry resolution: 30 minutes (if prepared)

Expertise Requirements

• Basic: Understanding of environment variables and CI/CD concepts
• Intermediate: TOML configuration and GitHub Actions workflow management
• Advanced: Database migration and rollback procedures

Financial Costs

• Minimum viable: $7/month (Render PostgreSQL)
• GitHub Actions: 2000 free minutes/month (timeout prevention critical)
• Shopify Partner: Free for development

Breaking Points and Warnings

Production Load Thresholds

• SQLite: Single concurrent user maximum
• PostgreSQL: Scales with hosting plan, generally unlimited for typical Shopify apps

Critical Dependencies

• CLI version: Pin to specific version (e.g., @shopify/cli@3.84.1) to prevent surprise breaks
• Node.js version: Use LTS versions only (Node 20 recommended)
• Token management: Maximum 2 active tokens per Partner account

Hidden Failure Modes

• Environment variable persistence: .env files don't deploy, must set in hosting dashboard
• SSL certificate issues: Development tunneling conflicts with production SSL
• Interactive prompts: Any CLI command without --force will hang in CI/CD

Success Indicators

• Deployment completes in under 5 minutes
• No authentication loops after deployment
• Database persists through deployments
• Rollback process tested and documented
• Token expiry monitoring in place