:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
"""CLI for hogbox previews. Mirrors bin/hobby-ci.py's subcommand shape so it
slots into the same CI flow.
# one-shot: provision + bring PostHog up, print the URL
python -m hogbox_preview up --branch "$BRANCH" --host "$HOG_HOST"
# granular (debug / staged CI), reusing a box:
python -m hogbox_preview create --host "$HOG_HOST"
python -m hogbox_preview seed --box-id box-xxxx --host "$HOG_HOST"
python -m hogbox_preview health --box-id box-xxxx --host "$HOG_HOST"
python -m hogbox_preview destroy --box-id box-xxxx --host "$HOG_HOST"
Layer is chosen with --backend (hogland today). The stack is identical across
layers — see stack.py.
"""
# ruff: noqa: T201 — this is a CLI; it prints results for CI to capture.
from __future__ import annotations
import os
import sys
import json
import argparse
import urllib.request
from hogland import APIError, Hogland
from . import timing
from .hogland_backend import HoglandBackend
from .stack import PostHogPreviewStack
DEFAULT_HOST = os.environ.get("HOG_HOST", "https://hogland-dev.hedgehog-kitefin.ts.net")
def build_backend(args: argparse.Namespace) -> HoglandBackend:
if args.backend != "hogland":
raise SystemExit(f"backend {args.backend!r} not wired up yet (see digitalocean_backend.py)")
return HoglandBackend(
host=args.host,
snapshot=args.snapshot,
web_port=args.web_port,
box_id=getattr(args, "box_id", None),
name=args.name,
cpus=args.cpus,
memory_mib=args.memory_mib,
disk_gib=args.disk_gib,
ttl_seconds=args.ttl_seconds,
)
def build_stack(backend: HoglandBackend, args: argparse.Namespace) -> PostHogPreviewStack:
return PostHogPreviewStack(
backend,
branch=getattr(args, "branch", None),
image=args.image,
seed_demo_data=not getattr(args, "no_seed", False),
reset_db=getattr(args, "reset_db", False),
frontend_dist_tar=getattr(args, "frontend_dist", None),
)
def cmd_up(args: argparse.Namespace) -> int:
backend = build_backend(args)
stack = build_stack(backend, args)
url = stack.bring_up()
print(f"box_id={backend.box_id}")
# Empty (not the literal "None") when there's no pen, so the CI parser treats
# it as absent rather than rendering an admin link to /pens/None.
print(f"pen_id={backend.pen_id or ''}")
print(f"url={url}")
if args.destroy:
backend.destroy()
print(f"destroyed {backend.box_id}")
return 0
def cmd_swap_frontend(args: argparse.Namespace) -> int:
# Deferred frontend swap onto an already-up box (parallel CI flow): `up`
# brings the box healthy on the :master SPA with no dist, then this lays the
# PR's freshly-built dist in once the runner finishes building it. Resolves
# the live box by pen/name — never restores a new one.
backend = build_backend(args)
stack = build_stack(backend, args)
url = stack.swap_frontend_only()
print(f"box_id={backend.box_id}")
print(f"url={url}")
return 0
def cmd_create(args: argparse.Namespace) -> int:
backend = build_backend(args)
backend.provision()
print(f"box_id={backend.box_id}")
print(f"url={backend.web_url}")
return 0
def cmd_migrate(args: argparse.Namespace) -> int:
backend = build_backend(args)
backend.provision()
build_stack(backend, args).migrate()
return 0
def cmd_seed(args: argparse.Namespace) -> int:
backend = build_backend(args)
backend.provision() # resolves the existing box when --box-id is set
build_stack(backend, args).generate_demo_data()
return 0
def cmd_health(args: argparse.Namespace) -> int:
backend = build_backend(args)
backend.provision()
# Spanned like the bring-up's own poll so `health --box-id` reports a
# summary too; without it this subcommand records no spans at all and
# write_summary has nothing to print.
with timing.span("health-poll"):
backend.wait_http_ok("/_health", expect=200, timeout=args.timeout)
# /_health only proves the process is up. Run the authed deep-health probe
# too so this subcommand catches an unusable app (the personhog-drift 500s
# slipped past /_health). --no-seed only tolerates a failed demo login
# (genuinely unseeded box); it no longer skips the probe outright.
build_stack(backend, args).deep_health()
print(f"healthy: {backend.web_url}")
return 0
def cmd_destroy(args: argparse.Namespace) -> int:
backend = build_backend(args)
backend.destroy()
print(f"destroyed {args.box_id or args.name}")
return 0
def _pr_state(repo: str, pr: str, token: str) -> str | None:
"""The GitHub state ("open"/"closed") of a PR, or None on any error."""
req = urllib.request.Request(
f"https://api.github.com/repos/{repo}/pulls/{pr}",
headers={"Authorization": f"Bearer {token}", "Accept": "application/vnd.github+json"},
)
try:
with urllib.request.urlopen(req, timeout=30) as r: # noqa: S310 — fixed GitHub host # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
return json.load(r).get("state")
except Exception: # noqa: BLE001 — a flaky check shouldn't reap a live preview
return None
def cmd_cleanup_stale(args: argparse.Namespace) -> int:
"""Reap previews whose PR is closed: list the caller's preview-pr-<n> pens,
check each PR's GitHub state, destroy (box + pen) the closed ones. Backstop
for a missed PR-close teardown — leaked boxes self-reap at their 24h preview
TTL, but pens have none, so this clears them. Honours DRY_RUN=true. Needs
GITHUB_REPOSITORY + GH_TOKEN/GITHUB_TOKEN; without them it can't tell stale
from live, so it keeps everything."""
repo = os.environ.get("GITHUB_REPOSITORY", "")
token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN") or ""
dry = os.environ.get("DRY_RUN", "false").lower() == "true"
if not (repo and token):
print("cleanup-stale: GITHUB_REPOSITORY + GH_TOKEN required to check PR state; nothing reaped")
return 0
client = Hogland(base_url=args.host, timeout=300)
reaped = 0
for pen in client.iter_pens():
name = getattr(pen, "name", "") or ""
if not name.startswith("preview-pr-"):
continue
pr = name[len("preview-pr-") :]
state = _pr_state(repo, pr, token)
if state != "closed":
print(f"{name}: PR #{pr} {state or 'unknown'} -> keep")
continue
print(f"{name}: PR #{pr} closed -> {'WOULD destroy' if dry else 'destroying'}")
if not dry:
HoglandBackend(host=args.host, name=name).destroy()
reaped += 1
print(f"cleanup-stale: reaped {reaped} closed-PR preview(s)")
return 0
def main(argv: list[str] | None = None) -> int:
p = argparse.ArgumentParser(prog="hogbox_preview", description=__doc__)
p.add_argument("--backend", default="hogland", help="preview layer (default: hogland)")
p.add_argument("--host", default=DEFAULT_HOST, help="hogland API host")
p.add_argument("--snapshot", default="alias:posthog-preview-golden", help="golden snapshot id/alias")
p.add_argument("--web-port", type=int, default=8000, help="in-guest port PostHog serves on")
p.add_argument("--image", default=PostHogPreviewStack.IMAGE, help="published posthog image")
p.add_argument(
"--name",
default="posthog-preview",
help="pen name / preview identity (e.g. preview-pr-123); boxes get a unique suffix",
)
# Sizing MUST match the golden snapshot being restored ("omit to inherit" is
# broken server-side). Defaults match the preview golden (snap-753bb8b3eeef,
# alias posthog-preview-golden) at 8 vCPU / 16 GB / 100 GB.
p.add_argument("--cpus", type=int, default=8, help="vCPUs (must match the golden's size)")
p.add_argument("--memory-mib", type=int, default=16384, help="memory MiB (must match the golden's size)")
p.add_argument("--disk-gib", type=int, default=100, help="rootfs GiB (must match the golden's size)")
p.add_argument(
"--ttl-seconds",
type=int,
default=1800,
help="idle TTL in seconds; hogland's reaper hibernates this on_idle=hibernate preview "
"after it's been idle this long (default 1800 = 30 min). A reviewer's next visit "
"wakes it in ~30s. Min 60.",
)
sub = p.add_subparsers(dest="cmd", required=True)
up = sub.add_parser("up", help="provision + bring PostHog up (one-shot)")
up.add_argument("--box-id", default=None, help="reuse an existing box instead of restoring a new one")
up.add_argument("--branch", default=None, help="posthog branch to check out in the box")
up.add_argument("--no-seed", action="store_true", help="skip demo-data seeding (generate_demo_data)")
up.add_argument(
"--reset-db",
action="store_true",
help="wipe pg+clickhouse first, so they migrate fresh & coherent with --image (use when baking a golden)",
)
up.add_argument("--destroy", action="store_true", help="tear the box down after (smoke-test mode)")
up.add_argument(
"--frontend-dist",
default=None,
help="path to a gzipped tar of a prebuilt frontend/dist; serves the PR's own frontend (else the image's :master SPA)",
)
up.set_defaults(func=cmd_up)
sf = sub.add_parser("swap-frontend", help="swap the PR frontend onto an already-up box (deferred, parallel CI)")
sf.add_argument("--box-id", default=None, help="attach to this box instead of resolving the pen by --name")
sf.add_argument(
"--frontend-dist",
required=True,
help="path to a gzipped tar of the prebuilt frontend/dist to serve (built on the CI runner)",
)
sf.set_defaults(func=cmd_swap_frontend)
cr = sub.add_parser("create", help="provision the box only")
cr.set_defaults(func=cmd_create)
mg = sub.add_parser("migrate", help="run postgres + clickhouse migrations on an existing box")
mg.add_argument("--box-id", required=True)
mg.set_defaults(func=cmd_migrate)
sd = sub.add_parser("seed", help="run demo-data seeding on an existing box")
sd.add_argument("--box-id", required=True)
sd.set_defaults(func=cmd_seed, no_seed=False)
he = sub.add_parser("health", help="wait for /_health, then run the authed deep-health probe")
he.add_argument("--box-id", required=True)
he.add_argument("--timeout", type=int, default=600)
he.add_argument("--no-seed", action="store_true", help="skip the authed deep-health probe (no demo user seeded)")
he.set_defaults(func=cmd_health)
de = sub.add_parser("destroy", help="tear a box down")
de.add_argument(
"--box-id", default=None, help="box to tear down (falls back to --name lookup, e.g. for CI cleanup)"
)
de.set_defaults(func=cmd_destroy)
sub.add_parser("cleanup-stale", help="reap previews whose PR is closed (cron backstop)").set_defaults(
func=cmd_cleanup_stale
)
args = p.parse_args(argv)
try:
return args.func(args)
except APIError as e:
# Surface the server's RFC 7807 problem-details body. The SDK exception
# message alone (e.g. "validation failed") hides which field the server
# rejected, which makes a CI failure undiagnosable from the log.
sys.stderr.write(f"[hogbox-preview] hogland API error (HTTP {e.status_code}): {e}\n")
if getattr(e, "body", None):
sys.stderr.write(f"[hogbox-preview] details: {json.dumps(e.body, indent=2, default=str)}\n")
raise
finally:
# Both paths. A failed run's partial timings are precisely how you tell a
# restore timeout from a migrate failure without opening the log, and
# that's the case where the log is least pleasant to read.
timing.write_summary()
if __name__ == "__main__":
sys.exit(main())