​

How Poindexter itself is tested and deployed

What this doc is. A transparency record of how Poindexter (the project, not your self-host) is tested and shipped to gladlabs.io. Kept here so that contributors can understand why a PR fails CI, what gets run on every push, and how changes reach production. What this doc isn’t. A recipe for setting up your own CI. If you want to run Poindexter on your own infrastructure, the only supported deployment is poindexter setup then bash scripts/start-stack.sh on a single machine.

​

The flow

Glad-Labs/poindexter (private GitHub, source of truth)
    │
    ├─→ GitHub Actions (several workflows — there is no single ci.yml)
    │       required checks: unit-tests.yml (job test-backend,
    │       backend pytest) + migrations-smoke.yml, on every PR +
    │       push to main (expensive steps short-circuit on docs-only
    │       changes — see "CI minutes / cost discipline" below)
    │       non-required, paths-gated: playwright-e2e.yml (frontend
    │       E2E), security.yml, grafana-panels-lint.yml
    │
    ├─→ Vercel (auto-deploy on push to main)
    │       └─→ www.gladlabs.io
    │
    └─→ sync-to-public-poindexter.yml (auto, filtered)
            │
            └─→ Glad-Labs/poindexter (public GitHub mirror)
                    │
                    ├─→ public-side CI checks
                    │       (test-backend, migrations-smoke,
                    │        Mintlify Deployment, link-rot)
                    │
                    └─→ Release Please runs for versioning only
                        (no deploy)

• docs.json: operator-branded gladlabs.io URLs are rewritten to poindexter-neutral GitHub URLs so OSS forks don’t inherit operator branding.
• CHANGELOG.md: lines mentioning operator-private values — private finance-module app_settings keys, Tailnet hostnames, or hardware-cost figures — are redacted before the mirror push.
• Operator-name regex: the leak guard uses [Mm]atthew (?:[A-Z]\.\s+)?[Gg]ladding (with optional middle-initial group) to catch both the plain and middle-initial forms of the operator name. Added in the 2026-05-27 security audit — the middle-initial form was slipping past the old [Mm]atthew [Gg]ladding pattern.

​

Debugging “Vercel is failing”

1. Check the Vercel dashboard — the deploy runs directly from the glad-labs-stack repo via Vercel’s GitHub integration, not via a GitHub Actions workflow.
2. Common build failure: next.config.js rejects localhost URLs in production. Set SKIP_ENV_VALIDATION=true in Vercel env vars, or ensure NEXT_PUBLIC_API_BASE_URL is set to a real URL (or left empty for static-only builds).
3. If tests fail locally: reproduce with docker exec poindexter-worker python -m pytest tests/unit/ -q. Frontend: cd web/public-site && npm run test.

​

Local vs CI environment differences

​

Key files

• .github/workflows/unit-tests.yml — backend pytest, exposed as the test-backend status check. One of the two branch-protection required checks; a detect-changes step short-circuits the expensive pytest steps on docs-only changes while still reporting green (a required check must always report — see “CI minutes / cost discipline” below). No deploy step.
• .github/workflows/migrations-smoke.yml — applies every migration against a clean Postgres + pgvector. The other branch-protection required check; fires on every PR + push to main.
• .github/workflows/playwright-e2e.yml — frontend E2E (Playwright), paths:-gated to web/public-site/**. Non-required. The frontend Jest unit run + JS lint are hook-only, not run in CI (see the workflow header).
• .github/workflows/security.yml / grafana-panels-lint.yml — non-required scans: gitleaks / trivy / sbom + path-specific lints, and the paths-gated Grafana panel lint, respectively.
• .github/workflows/sync-to-public-poindexter.yml — auto-mirror from glad-labs-stack to poindexter on every push to main.
• scripts/sync-to-github.sh — filter that runs inside the sync workflow. Strips operator-only files before pushing the public subset.
• .github/workflows/release-please.yml — Release Please on Glad-Labs/poindexter (the source repo — NOT the public mirror; running it on the force-rebuilt mirror broke versioning, see the workflow header). Versioning only. Runs daily at 08:00 UTC (was on: push to main) so a day’s feat:/fix: commits batch into one release instead of one-per-merge — the per-merge cadence 3×-amplified Actions-minute usage (each release commit re-ran the full suite AND re-triggered this workflow). workflow_dispatch cuts an ad-hoc release immediately.
• .github/workflows/regen-app-settings-doc.yml — nightly regen of docs/reference/app-settings.md against a clean Postgres seeded by the baseline migration. Opens a single PR on chore/regen-app-settings-doc when the file drifts; the branch is force-pushed every run so the PR always reflects the latest regen. Per poindexter#439.
• src/cofounder_agent/tests/ — Python unit tests (pytest). The test-backend check runs the full backend suite (several thousand cases; the exact count drifts as agents add tests, so it is not pinned here).
• web/public-site/next.config.js — has a validateEnv check that rejects localhost URLs in production. SKIP_ENV_VALIDATION=true bypasses for local dev.

​

CI minutes / cost discipline

• Only test-backend and migrations-smoke are branch-protection required checks. Required checks can’t be paths:-filtered — a skipped required check never reports, so it would block the PR forever; they keep firing and gate their expensive steps instead (see the detect-changes step in unit-tests.yml). Every other workflow is non-required and is paths:-filtered freely.
• playwright-e2e is paths:-gated to web/public-site/** + the playwright config + root package*.json. A backend/docs/infra change skips the Chromium build entirely (those specs only exercise the static Next.js site, so they can’t regress on a backend change).
• security.yml classifies changed paths first (the changes job), then runs only the relevant file-specific jobs (trivy-config / action-pins / shell-line-endings / poetry-lock). gitleaks / trivy-fs / sbom always run — a secret or CVE can land in any file. The weekly baseline + manual workflow_dispatch scans run every job regardless.
• grafana-panels-lint is paths:-gated to infrastructure/grafana/** + the lint script + migrations — the model the others copy.
• Release Please batches daily rather than per-merge (see Key files above).
• Deferred: a GitHub merge queue (would run the heavy suite once at merge instead of PR-then-post-merge-on-main) is intentionally NOT adopted yet — a merge queue amplifies flaky failures (an evicted entry rebuilds everything behind it), so it waits until the unit suite is reliably green. CodeQL is moving to advanced setup (PR + weekly schedule, paths-ignore for docs/infra) to drop its per-push-to-main scan — tracked as the fast-follow to this sweep.

​

Coverage (#995)

• test-backend is a required branch-protection check. A blind --cov-fail-under would block every PR before we even know the current percentage.
• The plan is a ratchet, not a target: read the baseline % from the first few CI runs (the Coverage report step log / the coverage-xml artifact), then set --cov-fail-under=<baseline> and bump it upward over time as coverage improves. The number only ever goes up — a PR that drops below the current floor fails; one that holds or improves passes. This avoids gating on the long tail while still catching regressions once a floor is set.

​

The public release repo is separate

​

Deploying the local worker (bringing prod up to main)

pwsh ./scripts/deploy-worker.ps1

Split-brain fix (glad-labs-stack#1295). Before this fix, deploy-worker.ps1 only fast-forwarded the dev checkout and left the deploy clone lagging up to 10 minutes behind origin/main. The script now explicitly syncs the deploy clone before restarting containers, and verifies the deploy clone HEAD matches origin/main before proceeding.

​

If you’re self-hosting Poindexter

poindexter setup --auto
bash scripts/start-stack.sh