Bootstrapping a Zero-Cost Engineering Journal: A Spec-Driven Approach

The Problem: The “SaaS Tax” on Personal Projects

Every modern blogging platform has a toll booth. Ghost wants $9/month. Netlify’s build minutes tick down every time your CMS auto-saves a draft. Even the “free” tiers extract payment in the form of vendor lock-in and opaque deployment cycles you don’t control.

For an engineering leader, that’s not just a budget line — it’s a broken contract. A personal site should be a demonstration of the same principles you’d apply to any production system: observable, automated, and operationally efficient. It shouldn’t cost you $100/year to publish three posts.

The Solution: The “Passive Host” Architecture

The fix isn’t a cheaper platform — it’s a better separation of concerns. By moving build compute to GitHub Actions and reducing Netlify to a pure CDN, I eliminated the metered build tax entirely. The result is a $0/month publishing workflow with a single, intentional cost event: the moment you decide something is ready to ship.

This is the Tag-Gated deployment model — production only moves when a v* Git tag fires.

Technical Stack

Component	Choice	Rationale
Framework	Astro	Zero JS overhead by default; high SEO performance
CMS	Decap CMS	Git-based; no database, content lives in the repo
Infrastructure	Netlify	Global CDN and Identity management
Orchestration	GitHub Actions	Bypasses Netlify’s metered build minutes via tag-gating

The “Zero-Waste” Deployment Logic

The key design decision is bypassing Netlify’s automatic build engine entirely. By using a GitHub Action triggered only on v* tags, I established a single gate that prevents accidental credit consumption during the drafting phase.

The Handshake

1. Drafting: Content is written in the CMS and committed to main as a raw Markdown file. Cost: $0.
2. Validation: npm run release pulls the latest CMS changes and bumps the semantic version.
3. Deployment: The Git tag triggers the GitHub Action, which builds the Astro site and ships the dist/ folder to Netlify via CLI. Cost: 15 Netlify build credits — the only billable event in the entire workflow.

The Wiring Spec: A Blueprint for Agentic Deployment

The secret to a $0-budget, zero-drift setup wasn’t the code — it was the Wiring Spec.

Before touching the Netlify dashboard or the AWS Console, I drafted a wiring.md file. This wasn’t documentation after the fact; it was the identity contract for the project — written upfront so that Claude Code, acting as an agentic CLI, could execute the setup sequentially without ambiguity.

The spec served as ground truth for three things:

• Site Initialization: Disabling Netlify’s internal build engine to prevent double-billing on build minutes
• The Auth Handshake: Mapping NETLIFY_SITE_ID and NETLIFY_AUTH_TOKEN to GitHub Secrets
• The Tag-Gate Logic: Restricting production deploys to Git tags to protect the monthly credit quota

Spec-first infrastructure isn’t just a habit from product work — it’s the interface contract for automated tooling. Every decision had a written rationale before a single CLI command ran.

The Zero-Waste Wiring Pattern

If you’re building this yourself, here is the architectural contract that keeps the operational budget at zero.

1. The Passive Host Strategy

Move build compute to GitHub Actions. Use Netlify strictly as a CDN.

Pro tip: Set your Netlify Build Command to # (null comment) and Publish Directory to . (current directory). This explicitly disables Netlify’s internal build engine — your GitHub Action ships the pre-built dist/ folder directly via CLI.

2. The CMS Bridge

Netlify Identity lets Decap CMS write directly to the repo — no OAuth complexity required.

• Enable Identity in Site Configuration → set Registration to Invite Only
• Enable Git Gateway under Services to create the secure bridge between the CMS UI and your GitHub files

3. The Deployment Handshake

Production is not triggered by a push to main. It’s gated by a Git tag.

A GitHub Action detects a v* tag, builds the Astro site on GitHub’s free runners, and ships the pre-built dist/ folder to Netlify via CLI. You spend build credits exactly once per intentional publish — not every time you fix a typo in a draft.

Lessons Learned

Spec-first is not just for product features — it’s the interface contract for automated tooling. Writing the wiring spec before touching any dashboard eliminated an entire category of debugging. Every infrastructure decision had a written rationale before a single CLI command ran.