Guide

Esecuzione in CI

Gating in CI tratta la policy di rilascio e il significato di ciascun codice di uscita. Questa pagina riguarda la parte che avviene all'interno di un job di CI: come installarvi Oloproof, dove risiede l'evidenza mentre il job è in esecuzione, come leggere un risultato senza analizzare una tabella e come confrontare una pull request con il branch a cui è destinata.

Il codice di uscita è il gate

oloproof run esce in base al proprio gate. Uno step di CI che lo esegue fallisce quando il gate blocca, che di solito è ciò che desideri e non richiede alcun collegamento aggiuntivo:

Codice	Uno step di CI dovrebbe
0	passare
1	fallire: una regola è fallita
2	fallire come build rotta: la configurazione era sbagliata e nulla è stato misurato
3	fallire, o avvisare: la suite non ha potuto decidere
4	fallire e passare la decisione a una persona
5	fallire come build rotta: l'esecuzione non è stata completata

Il codice 3 è quello su cui i team discutono. La policy predefinita blocca su di esso, perché una suite troppo piccola per decidere non ha dimostrato che la modifica sia sicura. Un team che vuole che il job diventi verde mentre fa crescere la propria suite può dichiararlo nella policy, anziché ignorando il codice di uscita:

version: 1
block_on: [FAIL, MANUAL_REVIEW]
warn_on: [INSUFFICIENT_EVIDENCE]
rules:
  - id: exact-label-floor
    metric: exact_label
    min: 0.70

La stessa esecuzione memorizzata di examples/support_bot/, che blocca con 3 sotto la propria policy, sotto questa:

oloproof gate RUN_ID --policy advisory.yaml

exact-label-floor: INSUFFICIENT_EVIDENCE (interval_overlaps_threshold)
  about 1614 more cases would decide it, if the observed rate holds (1632 in total)

Esce con 0. La decisione è invariata. Si è spostata solo l'azione di rilascio, e si è spostata perché lo dice un file sottoposto a revisione.

Leggere il risultato come dati

--json scrive un evento JSON per riga sullo standard output e le tabelle leggibili sullo standard error, così un log di CI conserva le tabelle e uno script legge gli eventi. Salvato in run.ndjson, l'id dell'esecuzione compare su ogni riga, e l'ultima riga riporta il codice di uscita:

jq -r 'select(.type == "run_started") | .run_id' run.ndjson
jq -c 'select(.type == "run_finished")' run.ndjson

run_01M3C3WS0SBTFAG55M7ECM1EZ4
{"run_id":"run_01M3C3WS0SBTFAG55M7ECM1EZ4","timestamp":"2026-09-25T11:06:03.646415Z","type":"run_finished","status":"DECIDED","completeness":"COMPLETE","exit_code":3}

Avanzamento e concorrenza elenca ogni tipo di evento.

Dove risiede l'evidenza

Un'esecuzione viene memorizzata in .oloproof/store.sqlite accanto all'oloproof.yaml da cui è stata avviata, e oloproof init aggiunge .oloproof/ a .gitignore. Un job di CI parte con uno store vuoto, quindi ogni job riesegue ogni caso, e nulla di un job è visibile al successivo.

Questo conta soprattutto per un confronto, che richiede entrambe le esecuzioni in uno stesso store. Due checkout di un progetto hanno ciascuno il proprio store, quindi un'esecuzione di baseline di uno non può essere trovata dall'altro:

Configuration error: unknown run 'run_01M3C3XSX9KY5T8VFZXA1CVBES'

OLOPROOF_HOME indirizza ogni comando verso un unico store, ovunque si trovi il suo oloproof.yaml. La directory che indica contiene .oloproof/store.sqlite.

Installare Oloproof in un job

Oloproof non è pubblicato su un indice di pacchetti, quindi non esiste una riga pip install che lo scarichi per nome. Un job lo installa da un checkout del repository di Oloproof, nello stesso modo in cui lo fa uno sviluppatore: actions/checkout con repository: che indica il luogo in cui risiede la copia di quel repository del tuo team, e un token: in grado di leggerlo se è privato. La radice del repository compila il pacchetto, e il pacchetto fornisce il comando oloproof.

Confrontare una pull request con la sua base

Fai il checkout del branch di base e della pull request fianco a fianco, esegui ciascuno nello stesso store e confronta:

name: oloproof
on: pull_request
jobs:
  evaluate:
    runs-on: ubuntu-latest
    env:
      OLOPROOF_HOME: ${{ github.workspace }}/evidence
    steps:
      - uses: actions/checkout@v4
        with:
          path: pr
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.base_ref }}
          path: main
      - uses: actions/checkout@v4
        with:
          repository: YOUR_ORG/Oloproof
          token: ${{ secrets.OLOPROOF_REPO_TOKEN }}
          path: oloproof-src
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: python -m pip install ./oloproof-src
      - run: mkdir -p "$OLOPROOF_HOME"
      - run: oloproof run --config main/oloproof.yaml --json > base.ndjson || true
      - run: oloproof run --config pr/oloproof.yaml --json > cand.ndjson || true
      - name: compare
        run: |
          candidate=$(jq -r 'select(.type == "run_started") | .run_id' cand.ndjson)
          baseline=$(jq -r 'select(.type == "run_started") | .run_id' base.ndjson)
          oloproof compare "$candidate" "$baseline" --config pr/oloproof.yaml --policy pr/compare.yaml

YOUR_ORG/Oloproof e OLOPROOF_REPO_TOKEN sono segnaposto per la tua copia del repository e per un secret in grado di leggerla. Le due esecuzioni riportano || true perché i loro gate non sono la questione qui; lo è il codice di uscita del confronto.

Gli stessi passaggi su un portatile, con il progetto generato dallo scaffold estratto due volte:

Comparison sha256:31ac104779bda1726ba55b661107cbe256fae5f1d831c79b1283a07651b58cbf of run_01M3C3XX4TM0WSZW8K81PHRGAW against run_01M3C3XW7X64B0Z0ACZV27WSW6 · 30 paired cases
exact_label: +0.0 points [-16.5, +16.5] · 30 paired · 0 missing · 0 excluded
Decisions
  no-regression  exact_label  non-inferiority, margin 5.0 points  INSUFFICIENT_EVIDENCE  interval_overlaps_margin
Gate: BLOCK (exit 3)

Entrambe le esecuzioni devono riguardare la stessa suite. Una pull request che modifica un caso cambia il digest della suite, e il confronto si rifiuta anziché appaiare casi che non sono più lo stesso caso:

Configuration error: runs 'run_01M3C3XXVZ1X0J2PR1ZW1WVGVZ' and 'run_01M3C3XW7X64B0Z0ACZV27WSW6' used different suites (sha256:baff4f101901d9a37cd440f99b9a70032f9488891b4f590f18a81017c26ba794 and sha256:2011286a7ec00c8c31560bb6d037b54a501a15f6251ac7c2d578d0c40e226d72); comparisons pair scenario by scenario over one suite

Un confronto con un'esecuzione non terminata esce con 5, come un gate su di essa: non c'è alcun risultato appaiato su cui decidere.

Dove andare dopo

Gating in CI tratta la policy e l'ordine in cui vengono riportati i codici di

uscita.

Regole di confronto tratta ciò che una policy di confronto può

chiedere.