Skip to Content
Quickstart

Quickstart

Get Stoney running on every Pull Request in under 5 minutes.

Stoney executes YAML-based contracts in CI to verify:

  • 🌐 API behavior (HTTP checks)
  • 🧰 Environment assumptions (exec checks)
  • 🗄️ Database invariants (SQL checks)

If a contract fails, the merge is blocked and Stoney reports exactly what drifted.

1) Create a Contract

Create:

contracts/smoke.yml

version: 1
feature: core
description: "Smoke checks"
 
contracts:
  - name: health
    checks:
      - id: health_ok
        work_item: "KAN-123"
        says: "Health endpoint must respond with 200 and ok=true"
        steps:
          - http:
              method: GET
              path: /health
            expect:
              status: 200
              json:
                ok: true

This defines a minimal invariant:

  • /health must return 200
  • body JSON must include { ok: true }

2) Add the GitHub Workflow

Create:

.github/workflows/stoney.yml

name: Stoney
 
on:
  pull_request:
  workflow_dispatch:
 
permissions:
  contents: read
  pull-requests: write
 
jobs:
  stoney:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: stoney-dev/stoney@v0
        with:
          base_url: ${{ secrets.STONEY_BASE_URL }}
          suite: "contracts/*.yml"
          comment_pr: "true"
 
          # Optional: stop after the first failing check (faster CI)
          # fail_fast: "true"

3) Add Your Base URL Secret

In GitHub:

Settings → Secrets and variables → Actions → New repository secret

Create:

  • Name: STONEY_BASE_URL
  • Value: https://staging.example.com

Open a Pull Request.

Stoney will:

  • Execute your contracts
  • Block the PR if invariants fail
  • Post a structured summary comment

Optional: Add a Database Invariant

contracts:
  - name: db_invariants
    checks:
      - id: db_smoke
        work_item: "KAN-125"
        says: "Database must be reachable"
        steps:
          - sql:
              driver: postgres
              url_env: STONEY_DB_URL
              query: "SELECT 1::int AS ok;"
            expect:
              rows: 1
              equals:
                ok: 1

Add secret:

  • STONEY_DB_URL → postgres://user:password@host:5432/db

If your database is private (VPN/VPC only), use a self-hosted runner inside your network.

Last updated on
IntroductionPhilosophy