.github/workflows/solo-ops-ci.yml

s.

Step 1: Infrastructure as Code & Immutable Deployments

Solo operations cannot tolerate drift. Every environment must be reproducible from version-controlled definitions. Use declarative configuration for compute, storage, and networking. Deployments should be immutable: each release creates a new artifact, never mutates a running instance.

Architecture Decision: Prefer managed PaaS/FaaS over self-hosted infrastructure. Self-hosting introduces patching, scaling, and security overhead that defeats solo leverage. Managed services abstract operational complexity while maintaining API-level control.

Step 2: Event-Driven Billing & Subscription Lifecycle

Manual billing reconciliation is a critical failure point. Integrate a payment provider with webhook-driven state management. All subscription changes must trigger idempotent handlers that update internal state, provision/deprovision features, and log audit trails.

// src/handlers/stripeWebhook.ts
import { createHmac } from 'crypto';
import { db } from '@/lib/db';
import { env } from '@/lib/env';

export async function handleStripeWebhook(rawBody: string, signature: string) {
  const expectedSignature = createHmac('sha256', env.STRIPE_WEBHOOK_SECRET)
    .update(rawBody)
    .digest('hex');

  if (!signature || !signature.includes(expectedSignature)) {
    throw new Error('Invalid Stripe signature');
  }

  const event = JSON.parse(rawBody);
  const { type, data } = event;

  const subscriptionId = data.object.id;
  const customerId = data.object.customer;

  switch (type) {
    case 'invoice.payment_succeeded':
      await db.subscription.upsert({
        where: { stripeSubscriptionId: subscriptionId },
        update: { status: 'active', currentPeriodEnd: new Date(data.object.lines.data[0].period.end * 1000) },
        create: { stripeSubscriptionId: subscriptionId, stripeCustomerId: customerId, status: 'active' }
      });
      break;

    case 'customer.subscription.deleted':
      await db.subscription.update({
        where: { stripeSubscriptionId: subscriptionId },
        data: { status: 'canceled', canceledAt: new Date() }
      });
      break;

    default:
      console.info(`Unhandled Stripe event: ${type}`);
  }

  return { received: true };
}

Step 3: Centralized Observability & Structured Logging

Solo founders cannot afford blind spots. All services must emit structured logs, metrics, and traces to a single aggregation pipeline. Alerting must be threshold-based, not noise-based.

Architecture Decision: Use OpenTelemetry-compatible agents that route to a managed observability platform. Avoid custom logging pipelines. Structured JSON logs with consistent correlation IDs enable instant trace reconstruction during incidents.

Step 4: Self-Healing Runbooks & Automated Rollbacks

Production failures must resolve without manual intervention. Implement health-check endpoints that trigger automatic rollback when error rates exceed defined thresholds.

// src/middleware/healthCheck.ts
import { Request, Response, NextFunction } from 'express';
import { db } from '@/lib/db';
import { redis } from '@/lib/redis';

export async function healthCheck(req: Request, res: Response, next: NextFunction) {
  const checks = {
    database: await db.$ping().catch(() => false),
    cache: await redis.ping().catch(() => false),
    external: await fetch(`${process.env.STATUS_ENDPOINT}/ping`).then(r => r.ok).catch(() => false)
  };

  const isHealthy = Object.values(checks).every(Boolean);
  const statusCode = isHealthy ? 200 : 503;

  res.status(statusCode).json({
    status: isHealthy ? 'healthy' : 'degraded',
    checks,
    timestamp: new Date().toISOString()
  });
}

Architecture Rationale

The solo ops stack prioritizes determinism over flexibility. Event-driven billing eliminates reconciliation drift. IaC prevents environment drift. Structured observability replaces guesswork with telemetry. Automated rollbacks replace panic with procedure. Each component is stateless where possible, idempotent by design, and routed through a single control plane. This architecture reduces cognitive load, enforces consistency, and scales operational bandwidth without adding headcount.

Pitfall Guide

1. Over-Engineering the MVP

Building custom authentication, billing, or analytics before product-market fit consumes engineering bandwidth that should go to core value delivery. Use managed, battle-tested services until revenue justifies abstraction.

2. Manual Deployment Gates

Bypassing CI/CD for "quick fixes" breaks pipeline integrity, introduces untested state, and makes rollbacks impossible. Every change, including hotfixes, must flow through the automated deployment chain.

3. Reactive Observability

Waiting for user reports to detect outages guarantees extended downtime. Implement proactive health checks, error rate thresholds, and latency percentiles before launch. Silence is not stability.

4. Context-Switching Without Timeboxing

Support tickets, billing inquiries, and deployment tasks fragment deep work blocks. Route all operational interruptions through a single ticketing system with defined SLAs. Batch operational tasks into fixed daily windows.

5. Security Debt Accumulation

Hardcoded secrets, missing rate limiting, and unscanned dependencies create exploitable surfaces. Enforce secret management, implement automated dependency scanning, and apply least-privilege IAM roles from day one.

6. Backup & Recovery Neglect

Automated backups are useless without tested restore procedures. Schedule periodic snapshot verification, document recovery steps, and run quarterly disaster drills. Unverified backups are equivalent to no backups.

7. Vendor Lock-In Without Abstraction

Tightly coupling business logic to a single provider's SDK creates migration friction. Implement adapter layers for critical services (billing, storage, notifications) to maintain portability without sacrificing managed convenience.

Best Practices from Production:

• Automate everything repeatable; if a task occurs twice, script it.
• Enforce idempotency in all external integrations; retries must not duplicate state.
• Maintain a single source of truth for operational state; avoid distributed configuration.
• Implement circuit breakers for third-party APIs to prevent cascade failures.
• Treat operational runbooks as code; version control, review, and test them like application logic.

Production Bundle

Action Checklist

• Initialize Infrastructure as Code: Provision compute, storage, and networking through declarative templates; enforce immutable deployments.
• Configure CI/CD Pipeline: Automate build, test, security scan, and deployment stages; require passing checks before merge.
• Implement Structured Observability: Deploy OpenTelemetry agents, route logs/metrics to a single dashboard, set alert thresholds.
• Automate Billing Lifecycle: Integrate webhook-driven subscription handlers; enforce idempotent state updates and audit logging.
• Deploy Self-Healing Runbooks: Add health-check endpoints, configure automatic rollback on error rate breaches, document recovery procedures.
• Enforce Security Baseline: Rotate secrets via vault, enable dependency scanning, apply rate limiting, verify IAM least-privilege roles.
• Validate Backup & Recovery: Schedule automated snapshots, run quarterly restore tests, maintain documented recovery runbooks.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Pre-revenue MVP	Managed PaaS + Serverless Functions	Zero infrastructure management; pay-per-use scales with traffic	$15–$40/mo
Post-traction Scaling	Containerized Workloads + Managed DB	Predictable performance; horizontal scaling without code rewrites	$120–$300/mo
High-Compliance Domain	VPC-Isolated Services + Audit Logging	Data residency control; automated compliance reporting	$250–$600/mo
Multi-Region Expansion	Global Edge Network + Regional Replicas	Reduced latency; fault isolation across geographic boundaries	$400–$900/mo

Configuration Template

# .github/workflows/solo-ops-ci.yml
name: Solo Founder CI/CD
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  NODE_VERSION: '20'
  CI: true

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run typecheck
      - run: npm run test:coverage
      - run: npx audit-ci --critical

  deploy:
    needs: validate
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ env.NODE_VERSION }}
          cache: 'npm'
      - run: npm ci --production
      - run: npm run build
      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'
      - name: Notify Observability
        run: curl -X POST ${{ secrets.OBSERVABILITY_WEBHOOK }} -d '{"event":"deploy","commit":"${{ github.sha }}"}'

// src/lib/observability.ts
import { trace, context, SpanStatusCode } from '@opentelemetry/api';
import { WinstonTransport } from './winston-otel';

export const tracer = trace.getTracer('solo-ops');

export async function instrumentOperation<T>(
  name: string,
  fn: () => Promise<T>
): Promise<T> {
  const span = tracer.startSpan(name);
  try {
    const result = await context.with(trace.setSpan(context.active(), span), fn);
    span.setStatus({ code: SpanStatusCode.OK });
    return result;
  } catch (error) {
    span.recordException(error as Error);
    span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
    throw error;
  } finally {
    span.end();
  }
}

Quick Start Guide

1. Initialize Project Structure: Run npx create-solo-ops@latest to scaffold a TypeScript monorepo with preconfigured CI/CD, observability agents, and billing webhook handlers.
2. Configure Environment Secrets: Populate .env with provider keys (Stripe, Vercel/Cloud, database URI). Run npx solo-ops vault:init to encrypt and sync secrets to your deployment platform.
3. Deploy Baseline Stack: Execute npm run infra:apply to provision managed compute, database, and storage. Trigger npm run deploy:prod to push the initial artifact through the automated pipeline.
4. Verify Operational Control Plane: Open the observability dashboard, confirm health-check endpoints return 200, and trigger a test Stripe webhook to validate subscription state updates. The system is now production-ready with zero manual intervention required.