Netlify Deploy Hooks Setup #

This document explains how to set up deploy hooks to ensure Netlify builds AFTER GitHub Actions syncs images to production.

Problem #

When merging staging → main for production deployment:

  1. Netlify immediately starts building
  2. GitHub Actions starts syncing images (preview → production)
  3. Race condition: Netlify builds before images are synced ❌

Solution #

Use Netlify Deploy Hooks to trigger production builds AFTER GitHub Actions completes the image sync.

Setup Instructions #

Step 1: Create the Deploy Hook #

Run the setup script (requires Netlify login):

npm run setup:deploy-hooks

This will create a build hook in Netlify and output a URL like:

https://hooks.netlify.com/abc123xyz...

Step 2: Add GitHub Secret #

  1. Copy the hook URL from Step 1
  2. Go to: https://github.com/cadextcp/RetroComputerDD/settings/secrets/actions
  3. Click "New repository secret"
  4. Name: NETLIFY_DEPLOY_HOOK_PRODUCTION
  5. Value: [paste the URL]

Step 3: Deploy to Production #

When you merge staging → main:

  1. GitHub Actions workflow triggers
  2. Images sync from Preview Supabase → Production Supabase
  3. GitHub Actions calls the Netlify deploy hook
  4. Netlify starts the production build
  5. Build uses the synced production images ✅

How It Works #

GitHub Actions Workflow #

.github/workflows/sync-images-to-production.yml:

jobs:
  sync-images:
    steps:
      # 1. Sync images from preview to production
      - name: Sync images from Preview to Production
        run: node scripts/sync-preview-to-production.js

      # 2. Trigger Netlify build (only if sync succeeded)
      - name: Trigger Netlify Production Build
        if: success()
        run: |
          curl -X POST -H "Content-Type: application/json" \
            -d '{}' "$"

Netlify Configuration #

netlify.toml:

[context.production]
  # Production builds are triggered by GitHub Actions
  # No upload needed - images already synced
  command = "npm run build-ci"

Testing #

To test the setup without deploying to production:

  1. Push to staging branch (normal behavior)
  2. When ready for production, create a PR to merge staging → main
  3. Check the Actions tab: https://github.com/cadextcp/RetroComputerDD/actions
  4. Verify images synced successfully
  5. Verify Netlify build started after sync

Troubleshooting #

Build still starts too early #

Check that the secret is set correctly:

# List secrets (requires GitHub CLI)
gh secret list

Hook URL not working #

Verify the hook exists in Netlify:

npx netlify hooks:list

Images not syncing #

Check the GitHub Actions logs:
https://github.com/cadextcp/RetroComputerDD/actions/workflows/sync-images-to-production.yml