Structural (0-60)
- Response missing: +25
- Fields removed: +20
- Type changes: +15
- Status code changed: +15
- Error class changed: +10
- Fields added: +5
Docs
CI Integration Guide
Gate every pull request on runtime behavior, not just test pass rates. Logito CI compares your application's runtime behavior against a baseline and blocks merges when behavioral drift exceeds your thresholds.
Overview
How it works
1
Capture
Your CI pipeline starts your application and runs your test suite. Logito captures runtime behavior during the test run.
2
Compare
Logito compares captured behavior against a baseline: API response shapes, latency, error rates, status codes, and retry patterns.
3
Gate
If drift exceeds your configured thresholds, the CI check fails and the PR is blocked. A summary is posted as a PR comment.
4
Report
Every CI run produces a structured summary showing what changed, what drifted, and what to investigate.
Setup
GitHub Actions
Add the following workflow to .github/workflows/logito-ci.yml:
name: Logito CI
on:
pull_request:
branches: [main]
permissions:
contents: read
pull-requests: write
env:
LOGITO_API_KEY: $\{\{ secrets.LOGITO_API_KEY \}\}
jobs:
logito-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Logito CLI
run: |
VERSION=$(gh release view --repo progadigital/homebrew-tap \\
--json tagName -q '.tagName' | sed 's/^v//')
curl -fsSL -o logito.tar.gz \\
"https://github.com/progadigital/homebrew-tap/releases/download/v$\{VERSION\}/logito_$\{VERSION\}_linux_amd64.tar.gz"
tar -xzf logito.tar.gz logito
install -m 755 logito /usr/local/bin/logito
env:
GH_TOKEN: $\{\{ github.token \}\}
- name: Start application
run: docker compose up -d && sleep 5 # your app start command
- name: Start capture
run: logito dev start --background
- name: Run tests
run: npm test # your test command
- name: Stop capture
run: logito dev stop || true
- name: Logito CI check
run: logito ci check
- name: Post summary to PR
if: always() && github.event_name == 'pull_request'
run: |
logito ci summary --run latest --format markdown > summary.md
gh pr comment $\{\{ github.event.number \}\} --body-file summary.md
env:
GH_TOKEN: $\{\{ secrets.GITHUB_TOKEN \}\} Required setup
- Create a query key at Sources > API Keys in the Logito dashboard
- Add it as a repository secret named
LOGITO_API_KEY - Replace the "Start application" and "Run tests" steps with your actual commands
Commands
CLI Reference
logito ci check [--run <id>]
Compare the current (or specified) run against its baseline and return a verdict:
- PASS (exit 0) — No significant behavioral drift. Safe to merge.
- WARNING (exit 0) — Some drift detected but below failure threshold. Proceed with caution.
- FAIL (exit 1) — Drift exceeds failure threshold. PR should not merge.
logito ci summary --run <id>
Generate a human-readable summary of a run. Supports --format markdown for PR comments. Shows the primary decision, recommended action, confidence level, and a link to the full dashboard view.
logito ci baseline [--run <id>]
Display the current baseline status. Shows whether the baseline is a running baseline (auto-selected from recent runs) or a pinned baseline (explicitly promoted by a user).
logito ci approve [--run <id>]
Promote a run to be the pinned baseline for its project and environment. Future runs will compare against this baseline until it is cleared or replaced. Use this after a known-good deployment to lock in the expected behavior.
Configuration
Drift Thresholds
Create a .logito/config.json file in your repository root to customize drift thresholds:
{
"ci": {
"drift_threshold_warn": 30,
"drift_threshold_fail": 60
}
} How drift scoring works
Logito computes a drift score (0-130) from three components:
Performance (0-40)
- Latency +150ms: +30
- Latency +60ms: +20
- Error rate +50%: +25
- Error rate +20%: +15
- Retries +5: +15
- Retries +2: +10
Stability (0-30)
- Flow violations: +10
- Flow failed: +10
- Critical alert: +15
- High alert: +10
- Medium alert: +5
Default thresholds: warn at 30, fail at 60. Lower thresholds make gating stricter. The config file is searched upward from the working directory.
Baselines
Understanding Baselines
Every CI check compares the current run against a baseline. There are two types:
Running baseline
Automatically selected from the most recent compatible run matching the same project and environment. Updates automatically as new runs complete. This is the default when no pinned baseline exists.
Pinned baseline
Explicitly promoted by a user or CI step via logito ci approve. Stays fixed until cleared or replaced. Use this after a known-good deployment to lock in expected behavior.
Typical workflow
- First run: No baseline yet. CI returns WARNING (non-blocking) while baseline forms.
- Second run onwards: Compared against the running baseline. Drift scoring applies.
- After a major release: Run
logito ci approveto pin the new baseline. - Ongoing: PRs are gated against the pinned baseline until the next promotion.
Troubleshooting
Common Issues
CI check returns WARNING on first run
Expected behavior. The first run has no baseline to compare against. Run the pipeline again to establish one, or use logito ci approve after verifying the run manually.
CI check fails but tests pass
Logito detects behavioral drift that unit tests don't cover: response shape changes, latency regressions, new error codes, or missing fields. Check the PR comment summary for specific findings.
API key not working
Use a query key for CI. CI integration requires a Business plan or higher. Check logito whoami to verify.
Drift score seems too sensitive
Lower your thresholds in .logito/config.json. Start with drift_threshold_warn: 40 and drift_threshold_fail: 80, then tighten as your baseline stabilizes.
Install