7 · Integrate into CI/CD

You've proven the suite runs green locally with odyssey ci review. The last step is to make that run happen automatically on every pull request, and to surface its verdict as a branded Dystopic check right on the PR — the same base-vs-head diff, the same exit codes, now gating your merges.

You wire this up by connecting your repo on the platform. The platform maps it to an umbrella agent that carries the gate and the suite binding (both authoritative, RBAC'd, audited), so CI runs with nothing committed but the workflow file — no config, no scenarios in the repo. The platform resolves the execution recipe and sources the bound suite's frozen scenarios server-side.

Connect your repo on the platform

When your repo is connected, the platform maps it to an umbrella agent that carries the CI execution recipe (run command, timeout, tools/ledger, credential refs), the gate, and the suite binding (ci_suite_id). The platform resolves all of that server-side — so a connected repo runs zero-yaml CI with nothing committed but the workflow file.

dystopic repo connect owner/name [--agent-id 42]   # claim the repo (auto-provisions an umbrella agent if unlinked)
dystopic repo status owner/name                    # connected? exit 0 / 1
dystopic repo list                                 # everything connected to your org

Once connected, configure the gate and suite on the umbrella agent — from the dashboard at https://platform.pipelines.tech (the gate card sets gate_config, the suite selector sets ci_suite_id) or from the CLI (dystopic agents gate set, dystopic agents ci-suite set — see 4 · Create a suite). The binding points CI at a frozen platform Suite. That's it: no per-repo config to maintain.

Run zero-yaml CI

A connected repo runs the check with no committed config. Point the CLI at the platform suite:

odyssey ci review --platform-suite

Under --platform-suite, each side submits no agent config and no seeds. The platform resolves the execution recipe from the connected repo's umbrella agent and sources the bound suite's frozen scenarios (byte-identical to an in-app check of that suite), stamping each side's source_git to that side's commit with a platform-minted App clone token.

The workflow file

.github/workflows/pipelines-regression.yml is the only file you commit to the repo. Scaffold it with dystopic ci init (offline; writes exactly this file plus the turn-it-on checklist) or copy it from the reference:

name: Dystopic regression

on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]
  # push:
  #   branches: [main]

permissions:
  contents: read
  checks: write
  pull-requests: write

concurrency:
  group: pipelines-regression-${{ github.ref }}
  cancel-in-progress: true

jobs:
  regression:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: BuildPipelines/pipelines-regression-action@v1
        with:
          api-key: ${{ secrets.DYSTOPIC_API_KEY }}
          platform-suite: true
        # env:
        #   ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Four lines in that template are load-bearing — don't strip them:

• platform-suite: true is what makes the action run zero-yaml: it passes --platform-suite, so the side submits no local config and the platform sources the bound CI suite's frozen scenarios. It requires an action release that includes the input (re-release @v1, or pin a revision that has it, if your copy predates SDK 0.5.0). The optional suite: input names a specific platform suite; the agent's bound CI suite wins server-side, else "default".

• fetch-depth: 0 on actions/checkout is required. On a pull request the action derives the base as the merge-base of the base branch and your PR head, and it materializes a worktree for each side — both commits must be present locally. A shallow checkout can't derive the merge-base and the check goes red.

• ready_for_review in types: closes the draft-PR hole. It is not a default pull_request event type. Without it, a check that skipped while the PR was a draft would hang "expected" forever once the PR flips to ready.

• concurrency + cancel-in-progress: true cancels superseded runs when you push again to the same PR, so rapid pushes don't burn runs on stale commits.

Turn it on

The workflow is inert until you complete the checklist. Three things, in order:

Once the key, the secret, and the App are in place, commit the workflow file and open a PR.

Open a PR and watch it land

With the key, the secret, and the App in place, open a pull request. Here's what happens — and the key design decision behind it.

The GitHub Action job is decoupled from the verdict. It submits the base and head runs, polls on a bounded budget, and then exits — it does not wait for the platform to finish grading. The platform completes the runs asynchronously, assembles the pairwise review, and posts (and updates) the branded Dystopic check-run via the GitHub App. The check typically appears within a few minutes.

Alongside the check, the App and action post a sticky PR comment carrying the per-scenario regression report — the same diff and findings you saw locally, with trace deep links into the platform review page.

What each trigger mode does

The action supports three GitHub event contexts, and the mode it runs in follows from the event:

• pull_request — base-vs-head. Base is the derived merge-base (stable per PR, which is what makes the base run cache-hittable). This is the default mode.
• merge_group (merge queues) — base-vs-head keyed on the event's own SHAs; the PR number is parsed from the queue ref.
• push — head-only. No base side; the pushed commit is graded against the suite's absolute thresholds (min_pass_rate only, no diff tiers). Uncomment the push: block in the workflow to gate merges to main this way.

Which check to require

When you set up a required check in branch protection, require the Actions job (the regression job), not only the App-posted Dystopic check. The job is guaranteed to reach a terminal state on every path — green skip, green submit, or a red gate exit — even if a platform outage means the App-posted check never lands. A required check that only watches the App-posted Dystopic slot could sit "expected" forever during an outage.

Outcomes that are not failures

A few outcomes exit green on purpose. Knowing them keeps you from chasing phantom failures:

• Fork PRs skip green. GitHub withholds secrets from fork PRs and hands them a read-only token, so no run can be submitted and no branded check can be posted. The action detects the fork and log-skips with a notice — never red. (Maintainers push the branch into the base repo and open an internal PR to run it.)
• Draft PRs skip green until marked ready — which is exactly why ready_for_review is in the trigger types.
• Poll-budget timeout exits 0. If the review is still assembling when the poll budget runs out, the job exits green with an in-progress notice; the platform finishes and posts the check asynchronously.
• Quota deferral (HTTP 429) exits 0. If the platform is at capacity it defers the submission neutrally — nothing was submitted, so there's no verdict. The action posts a neutral check and prints "platform busy … Re-run this job to retry." Capacity is not a verdict; re-run the job.

Where the gate comes from

A PR cannot weaken or remove its own gate. The gate is platform-authoritative, full stop.

The gate lives on the umbrella agent, set from the dashboard gate card (or dystopic agents gate set / PUT /api/agents/{id}/gate), and is authoritative (RBAC + audit). It cannot be weakened or removed by a PR — there is no base-vs-head weakening concept and no "gate weakened" banner. A platform-resolved base fails closed: dropping config on head turns the check red, it does not disarm it. Gate changes happen on the platform, not in a PR.

That's the flow

You've gone from a ported agent to a branded regression gate on every pull request: port → register → declare the world → author a suite → run checks → review findings → and now a Dystopic check that catches behavior regressions before they merge.