Aircast Deploy Bot

Automatic preview deployments for every pull request

How It Works

Every pull request to aircast-web or aircast-api automatically gets a preview deployment. No commands needed — just push code.

PR opened / pushed → Bot posts "⏳ Building..." comment with build progress → Bot dispatches build to source repo workflow → Source repo: checkout → install → lint → build → push Docker image → Source repo dispatches to gitops (ArgoCD ApplicationSet) → Gitops writes config.json → ArgoCD creates preview namespace → Gitops calls back to bot with build result → Bot polls preview URL until healthy (up to 90s) → Bot updates comment to "✅ Ready" with preview link PR closed / merged → Bot detects "preview" label → Bot dispatches cleanup to gitops → ArgoCD deletes preview namespace and resources

Commands

Comment on any PR to trigger these commands:

Command	Description	Example
`/deploy dev`	Create or rebuild preview	Forces a fresh preview build
`/deploy staging`	Deploy to staging	Updates staging image tag
`/deploy prod`	Deploy to production	Updates production image tag
`/destroy`	Tear down preview	Removes preview namespace
`/env set K=V`	Set env vars	`/env set VITE_DEBUG=true`
`/env list`	Show env vars	Lists current overrides
`/env clear`	Remove all env vars	Resets to defaults + rebuilds

Examples

Auto-deploy on PR open

Simply open a PR — the bot deploys automatically:

You: Open PR #42 with branch feat/new-feature

Bot: Adds preview label, posts comment:

### Preview Deployment
| Name | Status | Preview | Updated |
|------|--------|---------|--------|
| aircast-web | ⏳ Building (logs) | deploying... | abc12345 |

After build completes (~2-3 min):

### Preview Deployment
| Name | Status | Preview | Updated |
|------|--------|---------|--------|
| aircast-web | ✅ Ready (logs) | Visit Preview | abc12345 |

Build complete (2m 34s)
| Step | Status | Duration |
|------|--------|----------|
| Run actions/checkout | ✅ | 3s |
| Install dependencies | ✅ | 45s |
| Run linting | ✅ | 12s |
| Build frontend | ✅ | 1m 15s |
| Build and push Docker image | ✅ | 19s |

Override environment variables

You: Comment /env set VITE_PUBLIC_API_HOST=custom.api.com VITE_DEBUG=true

Bot: Reacts with 👍, stores env vars, triggers rebuild:

### Environment Variables Updated
| Variable | Value |
|----------|-------|
| VITE_PUBLIC_API_HOST | custom.api.com |
| VITE_DEBUG | true |

Redeploying preview with new config...

Deploy to staging

You: Comment /deploy staging

Bot: Reacts with 🚀, deploys PR branch to staging environment

Failed build

When a build fails, the bot shows the failed step and error output:

### Preview Deployment
| Name | Status | Preview | Updated |
|------|--------|---------|--------|
| aircast-web | ❌ Failed (logs) | — | abc12345 |

Build failed at: Run linting (1m 2s total)
| Step | Status | Duration |
|------|--------|----------|
| Run actions/checkout | ✅ | 3s |
| Install dependencies | ✅ | 45s |
| Run linting | ❌ | 14s |
| Build frontend | ⬜ | — |

Error: src/App.tsx(15,3): error TS2322: Type 'string' is
not assignable to type 'number'.

Environment Variables

Each preview environment can have custom env vars that override the defaults:

Set variables

/env set KEY1=value1 KEY2=value2

Multiple vars in one command. Triggers a rebuild with the new config.

List current

/env list

Shows all custom env vars for this PR's preview.

Clear all

/env clear

Removes all custom vars and rebuilds with defaults.

Common overrides

/env set VITE_PUBLIC_API_HOST=api.custom.test
/env set VITE_DEV_LOGIN_ENABLED=true
/env set VITE_PUBLIC_SFU_URL=wss://sfu.test

Build Log Streaming

The bot tracks build progress in real-time by polling GitHub Actions workflow steps:

During build: Shows step-by-step progress with durations in a collapsible section
On success: Shows all steps with total build time
On failure: Shows which step failed, with the last 20 lines of error output
Infrastructure steps (Set up job, Post cleanup, etc.) are filtered out for clarity

Dashboard

A web dashboard is available at /dashboard (requires GitHub OAuth login):

View all active preview environments across repos
Deploy or destroy previews from the UI
See deployment status, PR links, and preview URLs

Preview URLs

App	Preview URL Pattern	Example
aircast-web	`https://pr-{N}.app.dev.aircast.one`	pr-117.app.dev.aircast.one
aircast-api	`https://pr-{N}.api.dev.aircast.one`	pr-25.api.dev.aircast.one
aircast-website	`https://pr-{N}.www.dev.aircast.one`	pr-5.www.dev.aircast.one
aircast-sfu	`https://pr-{N}.sfu.dev.aircast.one`	pr-3.sfu.dev.aircast.one

Status Phases

Status	Meaning	What to do
⏳ Building	Source repo is building Docker image	Wait ~3 min for build to complete
🔨 Building (with progress)	Build in progress with step details	Expand to see which step is running
🔄 Deployed, syncing...	Image built, ArgoCD syncing	Wait ~30s for ArgoCD to sync
✅ Ready	Preview is live and health-checked	Click "Visit Preview"
⚠️ Deployed (not responding)	Health check timed out (90s)	Try again in a moment, check pod logs
❌ Failed	Build or deploy failed	Click "logs" link, check error output
⚪ Cancelled	Build cancelled (newer push)	New build auto-started for latest commit
🗑️ Destroyed	Preview cleaned up	Use /deploy dev to recreate

API Endpoints

Endpoint	Method	Auth	Description
`/`	GET	—	This documentation page
`/health`	GET	—	Health check (returns "ok")
`/metrics`	GET	—	Prometheus metrics
`/dashboard`	GET	GitHub OAuth	Deployment management UI
`/api/github/webhook`	POST	Webhook signature	GitHub webhook receiver
`/api/deploy/complete`	POST	Bearer token	Deploy completion callback

Supported Repos

Installed on all aircast-one repositories. Auto-deploy enabled for:

aircast-web — Frontend (React + TypeScript)
aircast-api — Backend (Go + Fiber)
aircast-sfu — Video relay (Go + WebRTC)
aircast-website — Marketing site

Other repos receive webhook events but won't auto-deploy previews (no ApplicationSet configured).

Architecture

Runtime: Go service on Kubernetes (dev-cluster)
Auth: GitHub App (JWT + installation tokens)
Deploy: ArgoCD ApplicationSet with git generator
Preview isolation: Separate K8s namespace per PR
TLS: cert-manager with Let's Encrypt
Observability: Prometheus metrics, structured JSON logs (Loki)
GC: Hourly scan for orphaned preview environments

Bot Status: Operational | Health | Metrics | Dashboard | Source Code