Skip to main content

​
Overview

Synapse automates the entire deployment process from code generation to live Shopify extension using GitHub, Fly.io, and Shopify CLI.

​
Architecture

User Prompt 
    ↓
Generated Code 
    ↓
MCP Validation
    ↓
GitHub Repository (branch per generation)
    ↓
Fly.io Service (auto-build via GitHub App)
    ↓
Shopify CLI Deploy (in Fly.io container)
    ↓
Live Extension in Dev Store

​
The Pipeline Steps

1

Code Commit

Validated code is committed to your personal GitHub repository
  • Repository: user-{userId}/synapse-extensions
  • Branch: gen-{generationId}
  • Files: Complete extension with configs
2

Fly.io Trigger

GitHub push triggers Fly.io build via GitHub App integration
  • Automatic build detection
  • buildpacks builder
  • Environment variables injected
3

Container Build

Fly.io builds a container with Shopify CLI and your extension
# Auto-generated by buildpacks
FROM node:20-alpine

# Install Shopify CLI
RUN npm install -g @shopify/cli

# Copy extension code
WORKDIR /app
COPY . .
RUN npm install

# Deploy command
CMD ["shopify", "app", "deploy", "--force"]
4

Shopify Deploy

Container runs Shopify CLI to deploy extension
shopify app deploy --force
shopify app release --version=latest --force
5

Completion

Extension is live and ready to configure in your store

​
GitHub Integration

​
Repository Structure

user-{userId}/
├── .github/
│   └── workflows/
│       └── deploy-flyio.yml    # Auto-deployment workflow
├── extensions/
│   └── {extension-name}/
│       ├── src/
│       │   ├── index.tsx         # Your code
│       │   └── run.graphql       # GraphQL queries
│       ├── shopify.extension.toml
│       └── tsconfig.json
├── shopify.app.toml
├── package.json
├── fly.toml                  # Fly.io config
└── Dockerfile

​
GitHub Actions Workflow

Every push automatically deploys: 
name: Deploy to Fly.io

on:
  push:
    branches: ['**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Deploy to Fly.io
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
        run: |
          brew install flyctl
          flyctl deploy --service ${{ secrets.FLY_APP_NAME }}

​
Branch Strategy

  • Per-Generation Branches
  • Main Branch
Each generation gets its own branch:
  • gen-abc123: First generation
  • gen-def456: Second generation
  • gen-ghi789: Third generation
Benefits:
  • Easy rollback
  • Compare versions
  • Independent deployments

​
Fly.io Configuration

​
Service Setup

Fly.io automatically creates a service for each generation: 
{
  "name": "shopify-user123-gen456",
  "source": {
    "type": "github",
    "repo": "user-123/synapse-extensions",
    "branch": "gen-456"
  },
  "build": {
    "builder": "nixpacks"
  },
  "deploy": {
    "numReplicas": 1,
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 10
  }
}

​
Environment Variables

Required environment variables are automatically set:
VariableDescriptionSource
SHOPIFY_CLIENT_IDApp client IDSynapse config
SHOPIFY_CLIENT_SECRETApp secretSynapse config
SHOPIFY_CLI_PARTNERS_TOKENPartners API tokenSynapse config
SHOPIFY_DEV_STORE_URLDevelopment store URLUser profile
FLY_API_TOKENFly.io project tokenAuto-generated

​
Build Process

Fly.io uses buildpacks to automatically detect and build:
Detected: package.json with React/TypeScriptBuild:
npm install
npm run build  # Runs shopify app build
Deploy:
shopify app deploy --force
Detected: package.json or Cargo.tomlBuild:
# JavaScript functions
npm install
shopify app function build

# Rust functions (if detected)
cargo build --release
Deploy:
shopify app deploy --force

​
Deployment Logs

View real-time deployment logs in the dashboard: 
🚀 Starting deployment for delivery-estimate...
📦 Pushing to GitHub: user-123/synapse-extensions:gen-abc123
✅ GitHub push complete
🚂 Fly.io build triggered
📦 Installing dependencies...
⚙️  Building extension...
✅ Build complete (12s)
🚀 Deploying to Shopify...
📤 Running shopify app deploy...
✅ Extension deployed: v2024.10.30.1
📤 Releasing version...
✅ Version released to dev store
🎉 Deployment complete! (28s total)

View in Partner Dashboard: https://partners.shopify.com/...
Configure in Store: Settings → Checkout → Customize

​
Monitoring

​
Fly.io Dashboard

Access your service in Fly.io:
  • Logs: Real-time deployment logs
  • Metrics: CPU, memory, network usage
  • Environment: Manage environment variables
  • Deployments: View deployment history
  • Settings: Configure domains, replicas

​
Shopify Partner Dashboard

View extensions in Partners:
  • Versions: All deployed versions
  • Status: Active, draft, or deprecated
  • Usage: Installation count
  • Analytics: Performance metrics

​
Troubleshooting Deployments

Cause: Dependency installation or build errorsSolutions:
  • Check Fly.io logs for error messages
  • Verify package.json dependencies
  • Ensure Node.js version compatibility
  • Review TypeScript compilation errors
Cause: Shopify CLI errors or authentication issuesSolutions:
  • Verify SHOPIFY_CLI_PARTNERS_TOKEN is valid
  • Check SHOPIFY_CLIENT_ID matches your app
  • Ensure dev store URL is correct
  • Review extension target compatibility
Cause: Extension not added to checkout editorSolutions:
  • Go to Settings → Checkout → Customize
  • Add extension from left sidebar
  • Save checkout configuration
  • Clear browser cache
Cause: Authentication or repository issuesSolutions:
  • Verify GitHub token permissions
  • Check repository exists
  • Ensure branch is not protected
  • Review GitHub Actions logs

​
Advanced Configuration

​
Custom Deployment Scripts

Override default deployment: 
// fly.toml
{
  "build": {
    "builder": "nixpacks",
    "buildCommand": "npm run custom-build"
  },
  "deploy": {
    "startCommand": "./custom-deploy.sh"
  }
}

​
Multi-Environment Setup

Deploy to different environments:
  • Development
  • Staging
  • Production
# Auto-deploys to dev store
SHOPIFY_DEV_STORE_URL=mystore-dev.myshopify.com

​
Rollback Strategy

Rollback to a previous version: 
# View deployment history
git log --oneline

# Rollback to specific commit
git checkout gen-abc123
git push --force origin gen-abc123

# Fly.io will automatically redeploy

​
Performance Metrics

MetricAverageBestWorst
GitHub Push2.1s0.8s5.2s
Fly.io Build18.3s12.1s45.7s
Shopify Deploy7.6s4.2s15.3s
Total Pipeline28.0s17.1s66.2s

​
Security

Encrypted Secrets

All tokens and secrets are encrypted at rest and in transit

Scoped Access

GitHub tokens have minimal required permissions

Isolated Services

Each user’s deployments run in isolated Fly.io services

Audit Logs

Complete deployment history for compliance

​
Next Steps

GitHub Setup

Configure GitHub repository and tokens

Fly.io Setup

Connect Fly.io and configure projects

Monitoring

Track and debug deployments

Best Practices

Optimize your deployment workflow