driveby

DriveBy — Documentation-Driven Testing for GitOps

Automated API quality gates powered by your OpenAPI spec. DriveBy validates APIs against 9 documentation-driven principles and blocks promotions when they fail — no manual QA, no broken deployments.

Developer opens PR → Webhook → Argo Events → DriveBy validation → Commit status → Merge or block

Why DriveBy?

Your OpenAPI spec already describes your API contract. DriveBy treats it as the single source of truth and validates your live API against it — automatically, on every PR.

• Spec-first quality gates — validates compliance, documentation, schemas, security, error handling, versioning
• GitOps-native — deploys as Crossplane custom resources, triggers via Argo Events webhooks
• Declarative — one YAML per API, one template per project. No scripts, no manual wiring
• PR feedback — commit status + PR comment with full validation report

How It Works

The Quality Gate Pipeline

┌──────────────────────────────────────────────────────────────────┐
│                        GitOps Repository                         │
│                                                                  │
│  Developer opens promotion PR (dev → staging)                    │
│       │                                                          │
│       ▼                                                          │
│  GitHub Webhook ──► Argo EventSource ──► Sensor                  │
│                                            │                     │
│                                            ▼                     │
│                                    Argo Workflow DAG              │
│                              ┌─────────────────────┐             │
│                              │  set-pending-status  │             │
│                              │         │            │             │
│                              │  wait-for-source     │             │
│                              │         │            │             │
│                              │  driveby validate    │ ◄── P001-P009
│                              │         │            │             │
│                              │  functional-test     │             │
│                              │        ╱ ╲           │             │
│                              │  report   comment-pr │             │
│                              └─────────────────────┘             │
│                                            │                     │
│       ┌────────────────────────────────────┘                     │
│       ▼                                                          │
│  Commit Status: success/failure                                  │
│       │                                                          │
│       ▼                                                          │
│  ✅ Merge allowed  ──► ArgoCD syncs staging                      │
│  ❌ PR blocked     ──► Fix and re-push                           │
└──────────────────────────────────────────────────────────────────┘

Crossplane Quality Gates

DriveBy uses a single Crossplane custom resource (XSDLC) to manage the entire promotion pipeline declaratively:

apiVersion: driveby.io/v1alpha1
kind: XSDLC
metadata:
  name: perfect-api
  namespace: driveby
spec:
  gitopsRepository:
    owner: novelcore
    name: perfect-api-gitops
  environments:
    - name: dev
    - name: staging
      gate:
        checks:
          - type: validate-only
            validationConfig:
              validationMode: test-ready
          - type: functional-test
    - name: prod
      autoMerge: false
      gate:
        checks:
          - type: validate-only
          - type: load-test
            loadTestConfig:
              concurrentUsers: 50
              testDuration: "2m"
              maxLatencyP95: "200ms"
              minSuccessRate: 0.995

Only two required fields: gitopsRepository (owner + name) and environments (minimum 2). Each environment can optionally define a gate with an ordered checks array — each check becomes a DAG step in the validation workflow.

Creates: ServiceAccount, EventBus, RBAC, WorkflowTemplates, EventSources, Sensors, Ingresses, ScmProvider, GitRepository, PromotionStrategy, ArgoCDCommitStatus, BranchProtection, deploy workflow

Add a new API? Apply one more XSDLC — that's it.

DDT Methodology

DriveBy implements Documentation-Driven Testing (DDT) — three axioms, nine validation principles:

Validation Modes

Installation

Kubernetes (recommended)

# 1. Install the Helm chart
helm install driveby oci://ghcr.io/meter-peter/charts/driveby \
  --version 2.0.0 \
  --set crossplane.enabled=true

# 2. Apply an XSDLC CR for your API
kubectl apply -f kubernetes/examples/novelcore-perfect-api/xsdlc-perfect-api.yaml

# 3. Configure GitHub webhook on your gitops repo
#    URL: https://<app>-webhook.<domain>/<app>-<trigger>

See docs/deployment-guide.md for the full guide with prerequisites, secrets, and verification checklist.

CLI Binary

# From GitHub Releases
curl -sL https://github.com/meter-peter/driveby/releases/latest/download/driveby_latest_linux_amd64.tar.gz | tar xz
sudo mv driveby /usr/local/bin/

# From source
git clone https://github.com/meter-peter/driveby.git
cd driveby/driveby-cli && go build -o driveby ./cmd/driveby

Docker

docker run --rm ghcr.io/meter-peter/driveby:latest validate-only \
  --openapi https://petstore3.swagger.io/api/v3/openapi.json \
  --host petstore3.swagger.io --protocol https --port 443 \
  --validation-mode strict

CLI Usage

# Validate API documentation (static analysis)
driveby validate-only --openapi openapi.json --host api.example.com --validation-mode strict

# Functional testing (live endpoint verification)
driveby function-only --openapi openapi.json --host api.example.com

# Load testing
driveby load-only --openapi openapi.json --host api.example.com \
  --concurrent-users 50 --test-duration 300

# Validate a public API by URL
driveby validate-only \
  --openapi https://petstore3.swagger.io/api/v3/openapi.json \
  --host petstore3.swagger.io --protocol https --port 443

Authentication

# Bearer token
driveby validate-only --openapi spec.json --host api.example.com \
  --auth-token "your-token"

# API key
driveby validate-only --openapi spec.json --host api.example.com \
  --auth-api-key "your-key" --auth-api-key-header "X-API-Key"

# Basic auth
driveby validate-only --openapi spec.json --host api.example.com \
  --auth-username "user" --auth-password "pass"

GitHub PR Integration

driveby validate-only --openapi spec.json --host api.example.com \
  --github-comment \
  --github-app-id "$APP_ID" \
  --github-installation-id "$INSTALL_ID" \
  --github-private-key "$PRIVATE_KEY" \
  --github-owner "your-org" --github-repo "your-repo" \
  --github-pr-number "$PR_NUMBER"

Full CLI reference: docs/CLI_USAGE.md

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                         │
│                                                              │
│  ┌──────────────────────────────────────────────────┐       │
│  │              driveby namespace                    │       │
│  │                                                   │       │
│  │  Crossplane XRD ──► Composition                    │       │
│  │       │                    │                       │       │
│  │       ▼                    ▼                       │       │
│  │  XSDLC (single CR per API)                        │       │
│  │  (RBAC + Workflows + Events + Ingress + Promoter) │       │
│  │                             │                      │       │
│  │  Argo Events: EventBus ◄───┘                      │       │
│  │       │                                           │       │
│  │  Webhook ──► Sensor ──► Argo Workflow             │       │
│  │                              │                     │       │
│  │                         DriveBy CLI               │       │
│  │                         (container)               │       │
│  └──────────────────────────────────────────────────┘       │
│                                                              │
│  ┌────────────────┐  ┌────────────────┐  ┌───────────────┐  │
│  │ app-dev/       │  │ app-staging/   │  │ app-prod/     │  │
│  │ (autoSync)     │──│ (gate-blocked) │──│ (autoSync)    │  │
│  └────────────────┘  └────────────────┘  └───────────────┘  │
└─────────────────────────────────────────────────────────────┘

Monorepo Structure

driveby-cli/     Go CLI — core validation engine (9 principles, spec abstraction)
kubernetes/      Helm chart (Crossplane XRDs + compositions, Argo Events/Workflows)
docs/            Deployment guide, quality gate SDLC, CLI reference
thesis/          LaTeX diploma thesis
tools/           Batch validation utilities
samples/         Example configs and reports

Configuration Model

DriveBy uses a two-tier configuration so every value can be overridden without editing chart source:

Resolution order (highest priority wins): XRD spec > values.yaml

Documentation

Contributing

See CONTRIBUTING.md for development setup, code standards, and how to add a new validation principle.

License

MIT — see LICENSE for details.