Deployment Pipeline

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

Code Commit

Validated code is committed to your personal GitHub repository

Repository: user-{userId}/synapse-extensions
Branch: gen-{generationId}
Files: Complete extension with configs

Fly.io Trigger

GitHub push triggers Fly.io build via GitHub App integration

Automatic build detection
buildpacks builder
Environment variables injected

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"]

Shopify Deploy

Container runs Shopify CLI to deploy extension

shopify app deploy --force
shopify app release --version=latest --force

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

Optionally merge approved generations to main:

git checkout main
git merge gen-abc123
git push origin main

Use for:

Production deployments
Stable releases
Team collaboration

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:

Variable	Description	Source
`SHOPIFY_CLIENT_ID`	App client ID	Synapse config
`SHOPIFY_CLIENT_SECRET`	App secret	Synapse config
`SHOPIFY_CLI_PARTNERS_TOKEN`	Partners API token	Synapse config
`SHOPIFY_DEV_STORE_URL`	Development store URL	User profile
`FLY_API_TOKEN`	Fly.io project token	Auto-generated

Build Process

Fly.io uses buildpacks to automatically detect and build:

UI Extensions

Detected: package.json with React/TypeScriptBuild:

npm install
npm run build  # Runs shopify app build

Deploy:

shopify app deploy --force

Functions

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

Build Failed

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

Deploy Failed

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

Extension Not Visible

Cause: Extension not added to checkout editorSolutions:

Go to Settings → Checkout → Customize
Add extension from left sidebar
Save checkout configuration
Clear browser cache

GitHub Push Failed

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

# Deploy to staging store
SHOPIFY_DEV_STORE_URL=mystore-staging.myshopify.com

# Deploy to production (manual approval)
SHOPIFY_STORE_URL=mystore.myshopify.com
REQUIRE_APPROVAL=true

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

Metric	Average	Best	Worst
GitHub Push	2.1s	0.8s	5.2s
Fly.io Build	18.3s	12.1s	45.7s
Shopify Deploy	7.6s	4.2s	15.3s
Total Pipeline	28.0s	17.1s	66.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

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

Deployment Pipeline

Overview

Architecture

The Pipeline Steps

GitHub Integration

Repository Structure

GitHub Actions Workflow

Branch Strategy

Fly.io Configuration

Service Setup

Environment Variables

Build Process

Deployment Logs

Monitoring

Fly.io Dashboard

Shopify Partner Dashboard

Troubleshooting Deployments

Advanced Configuration

Custom Deployment Scripts

Multi-Environment Setup

Rollback Strategy

Performance Metrics

Security

Encrypted Secrets

Scoped Access

Isolated Services

Audit Logs

Next Steps

GitHub Setup

Fly.io Setup

Monitoring

Best Practices

​Overview

​Architecture

​The Pipeline Steps

​GitHub Integration

​Repository Structure

​GitHub Actions Workflow

​Branch Strategy

​Fly.io Configuration

​Service Setup

​Environment Variables

​Build Process

​Deployment Logs

​Monitoring

​Fly.io Dashboard

​Shopify Partner Dashboard

​Troubleshooting Deployments

​Advanced Configuration

​Custom Deployment Scripts

​Multi-Environment Setup

​Rollback Strategy

​Performance Metrics

​Security

Encrypted Secrets

Scoped Access

Isolated Services

Audit Logs

​Next Steps

GitHub Setup

Fly.io Setup

Monitoring

Best Practices

Overview

Architecture

The Pipeline Steps

GitHub Integration

Repository Structure

GitHub Actions Workflow

Branch Strategy

Fly.io Configuration

Service Setup

Environment Variables

Build Process

Deployment Logs

Monitoring

Fly.io Dashboard

Shopify Partner Dashboard

Troubleshooting Deployments

Advanced Configuration

Custom Deployment Scripts

Multi-Environment Setup

Rollback Strategy

Performance Metrics

Security

Next Steps