GitHub Integration

Overview

Synapse uses GitHub as the source of truth for your generated extensions. Every generation creates a commit to your personal repository, triggering automatic deployment via Fly.io.

Benefits

Version Control

Complete history of all generations

Git commit per generation
Easy rollback
Compare versions
Branch management

Collaboration

Work with teams

Share repositories
Code reviews
Pull requests
CI/CD integration

Automatic Deploy

Push triggers deployment

No manual steps
Fly.io integration
Instant updates
Build logs

Backup & Recovery

Code is safe

Remote backup
Disaster recovery
Clone anywhere
Multi-environment

Setup Process

Generate GitHub Token

Create a Personal Access Token:

Go to GitHub Settings → Developer settings → Personal access tokens
Click “Generate new token (classic)”
Name it “Synapse Deployment”
Select scopes:
- ✅ repo (Full control of private repositories)
- ✅ workflow (Update GitHub Action workflows)
Click “Generate token”
Copy the token (you won’t see it again!)

Add Token to Synapse

Configure in your dashboard:

Go to Settings → Integrations
Find GitHub section
Paste your Personal Access Token
Click “Connect GitHub”
Verify connection succeeds

Repository Created

Synapse automatically creates:

Repository: user-{userId}/synapse-extensions
Initial commit with config files
GitHub Actions workflow
Branch protection (optional)

Test Generation

Generate an extension to verify:

Create any extension
Check GitHub repository
Verify commit appears
Confirm deployment triggers

Repository Structure

Your generated repository:

user-{userId}/synapse-extensions/
├── .github/
│   └── workflows/
│       └── deploy-flyio.yml    # Auto-deployment
├── extensions/
│   ├── delivery-estimate/
│   │   ├── src/
│   │   │   ├── Checkout.tsx
│   │   │   └── run.graphql
│   │   ├── shopify.extension.toml
│   │   └── package.json
│   └── volume-discount/
│       ├── src/
│       │   ├── run.rs
│       │   └── run.graphql
│       ├── shopify.extension.toml
│       └── Cargo.toml
├── shopify.app.toml              # App config
├── package.json                  # Dependencies
├── fly.toml                  # Fly.io config
├── Dockerfile                    # Container config
└── README.md                     # Documentation

GitHub Actions Workflow

Automatic deployment workflow:

name: Deploy to Fly.io

on:
  push:
    branches: ['**']  # Deploy all branches

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install Fly.io CLI
        run: brew install flyctl
      
      - name: Deploy to Fly.io
        env:
          FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}
          FLY_APP_NAME: ${{ secrets.FLY_APP_NAME }}
        run: |
          flyctl deploy --service $FLY_APP_NAME
      
      - name: Deploy to Shopify
        env:
          SHOPIFY_CLI_PARTNERS_TOKEN: ${{ secrets.SHOPIFY_CLI_PARTNERS_TOKEN }}
          SHOPIFY_CLIENT_ID: ${{ secrets.SHOPIFY_CLIENT_ID }}
          SHOPIFY_CLIENT_SECRET: ${{ secrets.SHOPIFY_CLIENT_SECRET }}
        run: |
          npm install -g @shopify/cli
          shopify app deploy --force
          shopify app release --version=latest --force

Branch Strategy

Per-Generation Branches
Main Branch
Feature Branches

Default: Each generation gets its own branch

main
├── gen-abc123-delivery-estimate
├── gen-def456-volume-discount
└── gen-ghi789-payment-banner

Benefits:

Isolated testing
Easy comparison
Independent deployment
Clean rollback

Usage:

# View all generations
git branch -a

# Switch to specific generation
git checkout gen-abc123

# Compare two generations
git diff gen-abc123 gen-def456

Production: Merge approved generations to main

# Merge generation to main
git checkout main
git merge gen-abc123
git push origin main

Benefits:

Single source of truth
Production stability
Team collaboration
Release management

Usage:

Review generation in branch
Test thoroughly
Merge when approved
Deploy from main

Custom: Create feature branches manually

# Create feature branch
git checkout -b feature/custom-checkout

# Make changes
git add .
git commit -m "feat: add custom fields"
git push origin feature/custom-checkout

# Create pull request
gh pr create --title "Custom checkout fields"

Benefits:

Manual control
Code review process
Team workflow
CI/CD integration

Commit Messages

Synapse uses conventional commit format:

# Extension generation
feat(extension): add delivery-estimate checkout extension

Generated extension: delivery-estimate
Type: checkout-ui
Target: purchase.checkout.delivery-address.render-after
Validation: PASSED
Generation ID: abc123

# Function generation
feat(function): add volume-discount function

Generated function: volume-discount
Type: discount
Language: Rust
Validation: PASSED
Generation ID: def456

# Updates
fix(extension): fix GraphQL query in delivery-estimate

# Manual changes
chore: update dependencies
docs: update README

Managing Your Repository

Clone Repository

Work on your extensions locally:

# Clone your repository
git clone https://github.com/user-{userId}/synapse-extensions.git
cd synapse-extensions

# Install dependencies
npm install

# Run Shopify dev server
npm run dev

Manual Edits

Make custom changes:

# Edit extension code
vi extensions/delivery-estimate/src/Checkout.tsx

# Test locally
npm run dev

# Commit changes
git add .
git commit -m "fix: improve delivery date formatting"
git push origin gen-abc123

# Synapse detects push and redeploys

Rollback

Revert to previous version:

# View commit history
git log --oneline

# Rollback to specific commit
git revert HEAD
git push origin gen-abc123

# Or force push previous commit
git reset --hard HEAD~1
git push --force origin gen-abc123

Compare Versions

See what changed:

# Compare two branches
git diff gen-abc123 gen-def456

# Compare specific file
git diff gen-abc123:extensions/delivery-estimate/src/Checkout.tsx \
         gen-def456:extensions/delivery-estimate/src/Checkout.tsx

# View changes in last commit
git show HEAD

GitHub Secrets

Required secrets (automatically configured by Synapse):

Secret	Purpose	Example
`FLY_API_TOKEN`	Fly.io API authentication	`rwy_xxx...`
`FLY_APP_NAME`	Target Fly.io service	`srv_xxx...`
`SHOPIFY_CLI_PARTNERS_TOKEN`	Shopify Partners API	`shppa_xxx...`
`SHOPIFY_CLIENT_ID`	App client ID	`abc123...`
`SHOPIFY_CLIENT_SECRET`	App client secret	`xyz789...`

To update secrets manually:

# Using GitHub CLI
gh secret set FLY_API_TOKEN --body "rwy_xxx..."

# Or via GitHub UI
# Settings → Secrets and variables → Actions → New repository secret

Advanced Configuration

Custom Workflows
Branch Protection
Multiple Environments

Add your own GitHub Actions:

# .github/workflows/test.yml
name: Test Extensions

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install
      
      - name: Run tests
        run: npm test
      
      - name: Type check
        run: npm run type-check

Protect main branch:Settings → Branches → Add rule:

Branch name pattern: main
✅ Require pull request reviews
✅ Require status checks to pass
✅ Require branches to be up to date
✅ Include administrators

Deploy to different environments:

# .github/workflows/deploy-staging.yml
name: Deploy to Staging

on:
  push:
    branches: ['staging']

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

Troubleshooting

Push Failed

Error: remote: Permission to user-xxx/synapse-extensions.git deniedCauses:

GitHub token expired
Insufficient permissions
Repository doesn’t exist

Solutions:

Regenerate GitHub token
Verify repo and workflow scopes
Check repository exists
Re-add token in Synapse settings

Workflow Not Running

Error: GitHub Actions workflow doesn’t triggerCauses:

Workflow disabled
Branch not matching pattern
Secrets missing

Solutions:

Check Actions tab in GitHub
Enable workflow if disabled
Verify branch name matches ** pattern
Confirm secrets are set

Merge Conflicts

Error: Cannot merge generation branchesCauses:

Multiple generations modify same file
Manual edits conflict with generations

Solutions:

# Update your branch
git fetch origin
git checkout gen-abc123
git rebase origin/main

# Resolve conflicts
# Edit files, then:
git add .
git rebase --continue
git push --force origin gen-abc123

Security Best Practices

Token Security

Keep tokens safe:

Never commit tokens to code
Use GitHub Secrets
Rotate regularly (every 90 days)
Minimal required scopes

Repository Privacy

Protect your code:

Use private repositories
Limit collaborator access
Enable 2FA on GitHub
Review access logs

Branch Protection

Prevent accidents:

Protect main branch
Require reviews
Enforce status checks
Restrict force push

Audit Trail

Track changes:

Review commit history
Monitor Actions runs
Check deployment logs
Enable notifications

Next Steps

Fly.io Setup

Configure Fly.io deployment

Deployment Pipeline

Understand the full pipeline

Best Practices

Optimize your workflow

Troubleshooting

Debug deployment issues

Get Started

Core Concepts

Building Extensions

Building Functions

Development

Deployment

Advanced

GitHub Integration

Overview

Benefits

Version Control

Collaboration

Automatic Deploy

Backup & Recovery

Setup Process

Repository Structure

GitHub Actions Workflow

Branch Strategy

Commit Messages

Managing Your Repository

GitHub Secrets

Advanced Configuration

Troubleshooting

Security Best Practices

Token Security

Repository Privacy

Branch Protection

Audit Trail

Next Steps

Fly.io Setup

Deployment Pipeline

Best Practices

Troubleshooting

​Overview

​Benefits

Version Control

Collaboration

Automatic Deploy

Backup & Recovery

​Setup Process

​Repository Structure

​GitHub Actions Workflow

​Branch Strategy

​Commit Messages

​Managing Your Repository

​GitHub Secrets

​Advanced Configuration

​Troubleshooting

​Security Best Practices

Token Security

Repository Privacy

Branch Protection

Audit Trail

​Next Steps

Fly.io Setup

Deployment Pipeline

Best Practices

Troubleshooting

Overview

Benefits

Setup Process

Repository Structure

GitHub Actions Workflow

Branch Strategy

Commit Messages

Managing Your Repository

GitHub Secrets

Advanced Configuration

Troubleshooting

Security Best Practices

Next Steps