GitHub Integration

Features

• PR Preview Comments — Automatic comments with deployment status and preview URLs
• Real-time Updates — Comments update as deployments progress (deploying → ready)
• Monorepo Support — Multiple sites from one repo with path filters
• Workflow Generation — Auto-generate GitHub Actions workflow files
• Consolidated Comments — One comment per PR, even for monorepos with multiple sites

How It Works

1. Install the GitHub App on your GitHub account or organization
2. Connect a site to a repository in the dashboard
3. Set up CI/CD with GitHub Actions (workflow file generated for you)
4. Push code — deployments automatically post comments on PRs

Setup Guide

Step 1: Install the GitHub App

Go to your site settings in the dashboard and click “Connect to GitHub”. You’ll be redirected to GitHub to install the ZeroDeploy app.

Choose which repositories to grant access to:

• All repositories — Access all current and future repos
• Select repositories — Choose specific repos (recommended)

Step 2: Connect Your Site

After installing the app, you’ll see your GitHub installations in the dashboard. Select the repository you want to connect to your site.

For monorepos, you can also configure:

• Root Directory — The subdirectory containing this site (e.g., apps/web)

Step 3: Generate Workflow File

Click “Generate Workflow” to get a GitHub Actions workflow file customized for your site. Copy this file to your repository:

# .github/workflows/zerodeploy.yml
name: Deploy to ZeroDeploy

on:
  push:
    branches: [main]
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build
      - name: Deploy to ZeroDeploy
        run: npx @zerodeploy/cli deploy --dir dist
        env:
          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}

Step 4: Add Deploy Token Secret

Create a deploy token and add it as a repository secret:

1. Create a token: zerodeploy token create "GitHub Actions" --site <site-id>
2. In GitHub, go to Settings → Secrets → Actions → New repository secret
3. Name: ZERODEPLOY_TOKEN
4. Value: Paste your deploy token

Customizing the Workflow

The generated workflow is a starting point. Here’s how to customize it for your project:

Build Configuration

The workflow has three main steps: Install → Build → Deploy. Customize each for your project:

steps:
  - uses: actions/checkout@v4

  # 1. Setup - choose your package manager
  - uses: actions/setup-node@v4
    with:
      node-version: '20'
      cache: 'npm'  # or 'yarn', 'pnpm'

  # 2. Install dependencies
  - run: npm ci  # or: yarn install --frozen-lockfile, pnpm install

  # 3. Build your app
  - run: npm run build

  # 4. Deploy the build output
  - run: npx @zerodeploy/cli deploy --dir dist
    env:
      ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}

The —dir Flag

The --dir flag must point to your build output directory, not your source code:

Using Different Package Managers

pnpm:

- uses: pnpm/action-setup@v2
  with:
    version: 8
- uses: actions/setup-node@v4
  with:
    node-version: '20'
    cache: 'pnpm'
- run: pnpm install
- run: pnpm run build

Bun:

- uses: oven-sh/setup-bun@v1
- run: bun install
- run: bun run build

Environment Variables

If your build requires environment variables, add them to the build step:

- run: npm run build
  env:
    VITE_API_URL: https://api.example.com
    VITE_PUBLIC_KEY: ${{ secrets.PUBLIC_KEY }}

Monorepo Working Directory

For monorepos, run commands in the correct directory:

# Install at root (for shared dependencies)
- run: npm ci

# Build in the app directory
- run: npm run build
  working-directory: apps/web

# Deploy the built output
- run: npx @zerodeploy/cli deploy web --dir apps/web/dist
  env:
    ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}

Preview vs Production Deploys

The CLI automatically detects PR deployments and creates previews instead of updating production. You can override this behavior:

# Force preview mode (even on main branch)
- run: npx @zerodeploy/cli deploy --dir dist --preview

# Force production deploy (even on PRs)
- run: npx @zerodeploy/cli deploy --dir dist --prod

PR Preview Comments

When you open a pull request or push commits, ZeroDeploy posts a comment showing deployment status:

## ZeroDeploy Preview

| Site | Status | Preview |
|------|--------|---------|
| **my-site** | ✅ Ready | [Open Preview](https://abc123-my-site.zerodeploy.app) |

---
**Commit:** `a1b2c3d`
**Updated:** 2024-01-15T10:30:00Z

Status updates in real-time:

Monorepo Setup

For monorepos with multiple sites, each site gets its own workflow file with path filters:

# .github/workflows/zerodeploy-web.yml
name: Deploy web to ZeroDeploy

on:
  push:
    branches: [main]
    paths:
      - 'apps/web/**'
      - 'packages/**'
      - 'package.json'
  pull_request:
    types: [opened, synchronize, reopened]
    paths:
      - 'apps/web/**'
      - 'packages/**'
      - 'package.json'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run build
        working-directory: apps/web
      - name: Deploy to ZeroDeploy
        run: npx @zerodeploy/cli deploy web --dir apps/web/dist
        env:
          ZERODEPLOY_TOKEN: ${{ secrets.ZERODEPLOY_TOKEN }}

Org-Scoped Tokens for Monorepos

Instead of creating a separate token for each site, create one org-scoped token that can deploy to any site in your organization:

# Create an org-scoped deploy token
zerodeploy token create "GitHub Actions" --org my-org

This single token works for all sites in the org, simplifying CI/CD setup for monorepos.

Consolidated PR Comments

When multiple sites deploy from the same PR, ZeroDeploy consolidates them into one comment:

## ZeroDeploy Previews

| Site | Status | Preview |
|------|--------|---------|
| **web** | ✅ Ready | [Open Preview](https://abc123-web.zerodeploy.app) |
| **dashboard** | ⚙️ Processing... | — |
| **admin** | 🚀 Deploying... | — |

---
**Commit:** `a1b2c3d`
**Updated:** 2024-01-15T10:30:00Z

Automatic CI Detection

The ZeroDeploy CLI automatically detects CI environments and extracts git metadata:

The CLI extracts:

• PR number — For posting comments
• Commit SHA — Shown in deployment details
• Branch name — For filtering deployments
• Commit message — For deployment context

You can override auto-detected values with CLI flags:

zerodeploy deploy \
  --pr 123 \
  --commit abc123def456... \
  --branch feature/my-feature \
  --commit-message "My commit message"

PR Cleanup

When a PR is closed (merged or abandoned), ZeroDeploy automatically cleans up preview deployments after 30 days. This is handled by the retention system to free up storage.

GitHub App Permissions

The ZeroDeploy GitHub App requests minimal permissions:

The app does not have access to:

• Your code content (only structure for workflow generation)
• Write access to your repository
• Issues, discussions, or other GitHub features
• Your GitHub access token

Troubleshooting

PR comment not appearing

• Verify the GitHub App is installed on the repository
• Check that the site is connected to the correct repository
• Ensure your deploy token is valid and has the correct scope
• Check the deployment logs for errors

Workflow not triggering

• Verify the workflow file is in .github/workflows/
• Check path filters match your changed files (for monorepos)
• Ensure the ZERODEPLOY_TOKEN secret is set correctly

Deployment failing in CI

• Check that your build command succeeds locally
• Verify the --dir flag points to your build output
• For monorepos, ensure the site slug is specified (or set via ZERODEPLOY_SITE env var)
• Check the CLI output for specific error messages