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

# GitHub Integration

> Connect GitHub for automatic deployment

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

<CardGroup cols={2}>
  <Card title="Version Control" icon="code-branch">
    Complete history of all generations

    * Git commit per generation
    * Easy rollback
    * Compare versions
    * Branch management
  </Card>

  <Card title="Collaboration" icon="users">
    Work with teams

    * Share repositories
    * Code reviews
    * Pull requests
    * CI/CD integration
  </Card>

  <Card title="Automatic Deploy" icon="rocket">
    Push triggers deployment

    * No manual steps
    * Fly.io integration
    * Instant updates
    * Build logs
  </Card>

  <Card title="Backup & Recovery" icon="cloud-arrow-up">
    Code is safe

    * Remote backup
    * Disaster recovery
    * Clone anywhere
    * Multi-environment
  </Card>
</CardGroup>

## Setup Process

<Steps>
  <Step title="Generate GitHub Token">
    Create a Personal Access Token:

    1. Go to [GitHub Settings → Developer settings → Personal access tokens](https://github.com/settings/tokens)
    2. Click "Generate new token (classic)"
    3. Name it "Synapse Deployment"
    4. Select scopes:
       * ✅ `repo` (Full control of private repositories)
       * ✅ `workflow` (Update GitHub Action workflows)
    5. Click "Generate token"
    6. Copy the token (you won't see it again!)
  </Step>

  <Step title="Add Token to Synapse">
    Configure in your dashboard:

    1. Go to Settings → Integrations
    2. Find GitHub section
    3. Paste your Personal Access Token
    4. Click "Connect GitHub"
    5. Verify connection succeeds
  </Step>

  <Step title="Repository Created">
    Synapse automatically creates:

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

  <Step title="Test Generation">
    Generate an extension to verify:

    1. Create any extension
    2. Check GitHub repository
    3. Verify commit appears
    4. Confirm deployment triggers
  </Step>
</Steps>

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

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

<Tabs>
  <Tab title="Per-Generation 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:**

    ```bash theme={null}
    # View all generations
    git branch -a

    # Switch to specific generation
    git checkout gen-abc123

    # Compare two generations
    git diff gen-abc123 gen-def456
    ```
  </Tab>

  <Tab title="Main Branch">
    **Production:** Merge approved generations to main

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

  <Tab title="Feature Branches">
    **Custom:** Create feature branches manually

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

## Commit Messages

Synapse uses conventional commit format:

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

<AccordionGroup>
  <Accordion title="Clone Repository" icon="clone">
    Work on your extensions locally:

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

  <Accordion title="Manual Edits" icon="pen">
    Make custom changes:

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

  <Accordion title="Rollback" icon="clock-rotate-left">
    Revert to previous version:

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

  <Accordion title="Compare Versions" icon="code-compare">
    See what changed:

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

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

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

<Tabs>
  <Tab title="Custom Workflows">
    Add your own GitHub Actions:

    ```yaml theme={null}
    # .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
    ```
  </Tab>

  <Tab title="Branch Protection">
    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
  </Tab>

  <Tab title="Multiple Environments">
    Deploy to different environments:

    ```yaml theme={null}
    # .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 }}
    ```
  </Tab>
</Tabs>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Push Failed">
    **Error:** `remote: Permission to user-xxx/synapse-extensions.git denied`

    **Causes:**

    * 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
  </Accordion>

  <Accordion title="Workflow Not Running">
    **Error:** GitHub Actions workflow doesn't trigger

    **Causes:**

    * 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
  </Accordion>

  <Accordion title="Merge Conflicts">
    **Error:** Cannot merge generation branches

    **Causes:**

    * Multiple generations modify same file
    * Manual edits conflict with generations

    **Solutions:**

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

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Token Security" icon="lock">
    Keep tokens safe:

    * Never commit tokens to code
    * Use GitHub Secrets
    * Rotate regularly (every 90 days)
    * Minimal required scopes
  </Card>

  <Card title="Repository Privacy" icon="eye-slash">
    Protect your code:

    * Use private repositories
    * Limit collaborator access
    * Enable 2FA on GitHub
    * Review access logs
  </Card>

  <Card title="Branch Protection" icon="shield">
    Prevent accidents:

    * Protect main branch
    * Require reviews
    * Enforce status checks
    * Restrict force push
  </Card>

  <Card title="Audit Trail" icon="list">
    Track changes:

    * Review commit history
    * Monitor Actions runs
    * Check deployment logs
    * Enable notifications
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Fly.io Setup" icon="train" href="/deployment/flyio-setup">
    Configure Fly.io deployment
  </Card>

  <Card title="Deployment Pipeline" icon="diagram-project" href="/concepts/deployment-pipeline">
    Understand the full pipeline
  </Card>

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

  <Card title="Troubleshooting" icon="wrench" href="/advanced/troubleshooting">
    Debug deployment issues
  </Card>
</CardGroup>