Deployment Architecture

---
name: deployment-architecture
description: "ShipIt deployment architecture: auto-deploy on push via platform Git integration, GitHub Deployments API for status tracking, deployment status in PR lifecycle card. Load when working on deployment features."
user-invocable: true
---

# Deployment Architecture

ShipIt uses **automatic deployments via platform Git integration** — no manual deploy button or
ShipIt-managed build. Users connect their repo to Vercel, Cloudflare Pages, or Netlify once, and
every push triggers the platform's native deploy pipeline. Since ShipIt auto-pushes after every
agent turn, deploys happen automatically.

## How It Works

1. User imports their GitHub repo on a hosting platform (Vercel, Cloudflare Pages, Netlify)
2. ShipIt's auto-push after agent turns triggers the platform's deploy pipeline
3. The platform creates GitHub Deployments on each deploy
4. ShipIt's `PrStatusPoller` fetches deployment status via the GitHub GraphQL API
5. Deployment status (URLs, state) appears in the PR lifecycle card

## Components

| Component | Location | Role |
|-----------|----------|------|
| `PrStatusPoller` | `orchestrator/pr-status-poller.ts` | Polls GitHub for PR + deployment status |
| `GitHubDeploymentStatus` | `shared/types/deployment-types.ts` | Type for deployment status data |
| `PrStatusSummary.deployments` | `shared/types/github-types.ts` | Deployment data on PR status |
| `DeploymentStatusRow` | `client/components/PrLifecycleCard.tsx` | UI row showing deploy status |
| Settings "Deployments" tab | `client/components/Settings.tsx` | Setup guide with platform links |

## Deployment Status Tracking

The `PrStatusPoller` GraphQL query includes `commit.deployments(last:5)` to fetch the latest
deployments for each PR's head commit. Each deployment includes:

- **environment** — e.g. "Production", "Preview"
- **state** — pending, success, failure, error, in_progress, etc.
- **environmentUrl** — the deployed URL (preview or production)
- **creator** — the platform that created the deployment (e.g. "vercel[bot]")

This data is broadcast via SSE `pr_status` events and displayed in the PR lifecycle card's
`DeploymentStatusRow` component.

## Setup Guide

The Settings dialog has a "Deployments" tab under the "Project" section that shows:
- Links to import repos on Vercel, Cloudflare Pages, and Netlify
- A brief explanation of how auto-deploy works with ShipIt

No credentials are stored — the platform's own Git integration handles auth.

## Key Design Decisions

- **No manual deploy button** — deploys happen on push, not on click
- **No ShipIt-managed builds** — the platform runs its own build with its own env vars
- **GitHub Deployments API** — platform-agnostic status tracking (works with any platform that
  creates GitHub Deployments)
- **No new credentials** — uses the existing GitHub token from PR polling
- **PR card only** — no toasts or notifications (deploys are frequent due to auto-push)