> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synapsebuilder.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment Pipeline

> GitHub, Fly.io, and Shopify CLI integration

## 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

<Steps>
  <Step title="Code Commit">
    Validated code is committed to your personal GitHub repository

    * Repository: `user-{userId}/synapse-extensions`
    * Branch: `gen-{generationId}`
    * Files: Complete extension with configs
  </Step>

  <Step title="Fly.io Trigger">
    GitHub push triggers Fly.io build via GitHub App integration

    * Automatic build detection
    * buildpacks builder
    * Environment variables injected
  </Step>

  <Step title="Container Build">
    Fly.io builds a container with Shopify CLI and your extension

    ```dockerfile theme={null}
    # 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"]
    ```
  </Step>

  <Step title="Shopify Deploy">
    Container runs Shopify CLI to deploy extension

    ```bash theme={null}
    shopify app deploy --force
    shopify app release --version=latest --force
    ```
  </Step>

  <Step title="Completion">
    Extension is live and ready to configure in your store
  </Step>
</Steps>

## 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:

```yaml theme={null}
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

<Tabs>
  <Tab title="Per-Generation Branches">
    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
  </Tab>

  <Tab title="Main Branch">
    Optionally merge approved generations to `main`:

    ```bash theme={null}
    git checkout main
    git merge gen-abc123
    git push origin main
    ```

    **Use for:**

    * Production deployments
    * Stable releases
    * Team collaboration
  </Tab>
</Tabs>

## Fly.io Configuration

### Service Setup

Fly.io automatically creates a service for each generation:

```json theme={null}
{
  "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:

<AccordionGroup>
  <Accordion title="UI Extensions" icon="react">
    **Detected:** `package.json` with React/TypeScript

    **Build:**

    ```bash theme={null}
    npm install
    npm run build  # Runs shopify app build
    ```

    **Deploy:**

    ```bash theme={null}
    shopify app deploy --force
    ```
  </Accordion>

  <Accordion title="Functions" icon="function">
    **Detected:** `package.json` or `Cargo.toml`

    **Build:**

    ```bash theme={null}
    # JavaScript functions
    npm install
    shopify app function build

    # Rust functions (if detected)
    cargo build --release
    ```

    **Deploy:**

    ```bash theme={null}
    shopify app deploy --force
    ```
  </Accordion>
</AccordionGroup>

## 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

<AccordionGroup>
  <Accordion title="Build Failed">
    **Cause:** Dependency installation or build errors

    **Solutions:**

    * Check Fly.io logs for error messages
    * Verify `package.json` dependencies
    * Ensure Node.js version compatibility
    * Review TypeScript compilation errors
  </Accordion>

  <Accordion title="Deploy Failed">
    **Cause:** Shopify CLI errors or authentication issues

    **Solutions:**

    * Verify `SHOPIFY_CLI_PARTNERS_TOKEN` is valid
    * Check `SHOPIFY_CLIENT_ID` matches your app
    * Ensure dev store URL is correct
    * Review extension target compatibility
  </Accordion>

  <Accordion title="Extension Not Visible">
    **Cause:** Extension not added to checkout editor

    **Solutions:**

    * Go to Settings → Checkout → Customize
    * Add extension from left sidebar
    * Save checkout configuration
    * Clear browser cache
  </Accordion>

  <Accordion title="GitHub Push Failed">
    **Cause:** Authentication or repository issues

    **Solutions:**

    * Verify GitHub token permissions
    * Check repository exists
    * Ensure branch is not protected
    * Review GitHub Actions logs
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Custom Deployment Scripts

Override default deployment:

```json theme={null}
// fly.toml
{
  "build": {
    "builder": "nixpacks",
    "buildCommand": "npm run custom-build"
  },
  "deploy": {
    "startCommand": "./custom-deploy.sh"
  }
}
```

### Multi-Environment Setup

Deploy to different environments:

<Tabs>
  <Tab title="Development">
    ```bash theme={null}
    # Auto-deploys to dev store
    SHOPIFY_DEV_STORE_URL=mystore-dev.myshopify.com
    ```
  </Tab>

  <Tab title="Staging">
    ```bash theme={null}
    # Deploy to staging store
    SHOPIFY_DEV_STORE_URL=mystore-staging.myshopify.com
    ```
  </Tab>

  <Tab title="Production">
    ```bash theme={null}
    # Deploy to production (manual approval)
    SHOPIFY_STORE_URL=mystore.myshopify.com
    REQUIRE_APPROVAL=true
    ```
  </Tab>
</Tabs>

### Rollback Strategy

Rollback to a previous version:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Encrypted Secrets" icon="lock">
    All tokens and secrets are encrypted at rest and in transit
  </Card>

  <Card title="Scoped Access" icon="key">
    GitHub tokens have minimal required permissions
  </Card>

  <Card title="Isolated Services" icon="shield">
    Each user's deployments run in isolated Fly.io services
  </Card>

  <Card title="Audit Logs" icon="list">
    Complete deployment history for compliance
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="GitHub Setup" icon="github" href="/deployment/github-integration">
    Configure GitHub repository and tokens
  </Card>

  <Card title="Fly.io Setup" icon="train" href="/deployment/flyio-setup">
    Connect Fly.io and configure projects
  </Card>

  <Card title="Monitoring" icon="chart-line" href="/advanced/debugging">
    Track and debug deployments
  </Card>

  <Card title="Best Practices" icon="star" href="/advanced/best-practices">
    Optimize your deployment workflow
  </Card>
</CardGroup>