Guías

Ejecución en CI

Gates en CI trata la política de publicación y lo que significa cada código de salida. Esta página cubre lo que ocurre dentro de un job de CI: cómo instalar Oloproof allí, dónde se guarda la evidencia mientras el job se ejecuta, cómo leer un resultado sin analizar una tabla y cómo comparar un pull request con la rama a la que apunta.

El código de salida es el gate

oloproof run termina con el código de su gate. Un paso de CI que lo ejecuta falla cuando el gate bloquea, que suele ser lo deseado y no requiere configuración adicional:

Código	Un paso de CI debería
0	pasar
1	fallar: una regla falló
2	fallar como build roto: la configuración era incorrecta y no se midió nada
3	fallar, o advertir: la suite no pudo decidir
4	fallar y derivarse a una persona
5	fallar como build roto: la ejecución no terminó

El código 3 es el que genera discusión en los equipos. La política por defecto bloquea con él, porque una suite demasiado pequeña para decidir no ha demostrado que el cambio sea seguro. Un equipo que quiera que el job quede en verde mientras amplía su suite puede indicarlo en la política, en lugar de ignorar el código de salida:

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

La misma ejecución almacenada de examples/support_bot/, que bloquea con 3 bajo su propia política, con esta otra:

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)

Termina con 0. La decisión no cambia. Solo cambió la acción de publicación, y cambió porque lo dice un archivo sujeto a revisión.

Leer el resultado como datos

--json escribe un evento JSON por línea en la salida estándar y las tablas legibles en la salida de error estándar, de modo que el log de CI conserva las tablas y un script lee los eventos. Guardado en run.ndjson, el id de la ejecución aparece en cada línea, y la última línea incluye el código de salida:

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}

Progreso y concurrencia enumera todos los tipos de evento.

Dónde se guarda la evidencia

Una ejecución se almacena en .oloproof/store.sqlite, junto al oloproof.yaml desde el que se ejecutó, y oloproof init añade .oloproof/ a .gitignore. Un job de CI empieza con un almacén vacío, por lo que cada job vuelve a ejecutar todos los casos, y nada de un job es visible para el siguiente.

Esto importa sobre todo en una comparación, que necesita ambas ejecuciones en un mismo almacén. Dos checkouts de un proyecto tienen cada uno su propio almacén, así que una ejecución de línea base hecha desde uno no se encuentra desde el otro:

Configuration error: unknown run 'run_01M3C3XSX9KY5T8VFZXA1CVBES'

OLOPROOF_HOME hace que todos los comandos usen un mismo almacén, dondequiera que esté su oloproof.yaml. El directorio que indica contiene .oloproof/store.sqlite.

Instalar Oloproof en un job

Oloproof no está publicado en ningún índice de paquetes, así que no existe una línea pip install que lo descargue por nombre. Un job lo instala desde un checkout del repositorio de Oloproof, igual que lo hace un desarrollador: actions/checkout con repository: apuntando a donde esté la copia de ese repositorio de su equipo, y un token: que pueda leerlo si es privado. La raíz del repositorio construye el paquete, y el paquete proporciona el comando oloproof.

Comparar un pull request con su base

Haga checkout de la rama base y del pull request uno junto al otro, ejecute cada uno en el mismo almacén y compare:

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 y OLOPROOF_REPO_TOKEN son marcadores de posición para su copia del repositorio y un secreto que pueda leerlo. Las dos ejecuciones llevan || true porque sus propios gates no son la cuestión aquí; lo es el código de salida de la comparación.

Los mismos pasos en un portátil, con el proyecto generado clonado dos veces:

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)

Ambas ejecuciones deben ser sobre la misma suite. Un pull request que edita un caso cambia el digest de la suite, y la comparación se niega a continuar en lugar de emparejar casos que ya no son el mismo 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

Una comparación de una ejecución que no terminó sale con 5, igual que un gate sobre una: no hay resultado emparejado sobre el que decidir.

Siguientes pasos

Gates en CI trata la política y el orden en que se informan los códigos de salida.
Reglas de comparación trata lo que puede exigir una política de comparación.