AI CodeOps

El control de publicación en CI

Llama al control de publicación de AI CodeOps desde GitHub Actions, GitLab CI, Bitbucket Pipelines, Forgejo o Gitea, haz fallar el job si deniega y conviértelo en una comprobación obligatoria.

El control de publicación responde a una pregunta para tu pipeline: ¿puede entregarse este pull request? Tu CI envía la URL del pull request a POST /api/release/check con una clave de API del espacio de trabajo. AI CodeOps mira todas las sesiones que tocaron el cambio y responde allowed: true o allowed: false, con motivos como pruebas que fallan, un hallazgo abierto de gravedad high o critical, una revisión que no terminó o un build del repositorio que no pasó. También deniega una sesión que cambió código y no tiene un resultado de pruebas con recuentos, salvo que el proyecto tenga activado Don't run tests for this project. Son las mismas reglas que los controles de calidad de la consola.

AI CodeOps abre sus pull requests desde ramas llamadas codeops/run-<id>. El control deniega un cambio que no tocó ninguna sesión de AI CodeOps, así que los jobs de más abajo solo preguntan por esas ramas. Tus demás comprobaciones se siguen ejecutando en todos los pull requests.

Crea una clave de API

  1. En la consola, abre Configure → API Keys y crea una clave. El secreto empieza por sk- y se muestra una sola vez.
  2. Guárdalo en el almacén de secretos de tu sistema de CI con el nombre AICODEOPS_API_KEY. No lo pongas en el repositorio.
Sistema de CIDónde va el secreto
GitHub ActionsSettings → Secrets and variables → Actions del repositorio, como secreto del repositorio
GitLab CISettings → CI/CD → Variables, enmascarado
Bitbucket PipelinesRepository settings → Repository variables, con Secured marcado
Forgejo y Gitea ActionsSettings → Actions → Secrets del repositorio

En GitLab, deja Protect variable desactivado salvo que tus ramas codeops/* estén protegidas. Una variable protegida solo se da a los pipelines de ramas protegidas, así que el job recibiría una clave vacía.

La clave actúa como el miembro que la creó y necesita el permiso workspace:read. Donde tu plan incluya la limitación del alcance de las claves, un administrador puede limitar la clave a la comprobación del control de publicación. Hay más información sobre las claves en Claves de API del espacio de trabajo.

Los jobs de más abajo llaman a https://console.aicodeops.dev. Usa el host en el que abres la consola. La página Release gate de la consola, en Review & Gate, muestra los jobs de GitHub Actions y de GitLab CI con tu dirección ya rellenada y un botón Copy.

Añade el job

Cada job envía la URL del pull request, imprime el resumen y los motivos, y falla salvo que la respuesta sea allowed: true. El endpoint responde 200 también ante una denegación, así que el job lee el campo, no el código de estado. curl --fail convierte una clave incorrecta, un límite de peticiones o una interrupción del servicio en un job fallido.

GitHub Actions

Guarda esto como .github/workflows/aicodeops-release-gate.yml:

name: AI CodeOps release gate
on:
  pull_request:

permissions:
  contents: read

jobs:
  release-gate:
    name: AI CodeOps release gate
    # AI CodeOps opens its pull requests from codeops/run-<id> branches.
    if: startsWith(github.head_ref, 'codeops/run-')
    runs-on: ubuntu-latest
    steps:
      - name: Ask the release gate
        env:
          AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
          AICODEOPS_URL: https://console.aicodeops.dev
          PR_URL: ${{ github.event.pull_request.html_url }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          body=$(jq -n --arg pr "$PR_URL" --arg sha "$HEAD_SHA" '{pullRequestURL: $pr, commitSHA: $sha}')
          response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
            -H "Authorization: Bearer $AICODEOPS_API_KEY" \
            -H "Content-Type: application/json" \
            -d "$body") || { echo "::error::Release check unavailable: failing closed"; exit 1; }
          echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
          if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
            echo "::error::AI CodeOps release gate denied this change"
            exit 1
          fi

Envía la URL del pull request y su commit de cabecera. Una sesión coincide con cualquiera de los dos.

GitLab CI

Añade este job a .gitlab-ci.yml:

aicodeops-release-gate:
  image: alpine:3.20
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    AICODEOPS_URL: https://console.aicodeops.dev
  before_script:
    - apk add --no-cache curl jq
  script:
    - |
      case "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME" in
        codeops/run-*) ;;
        *) echo "Not an AI CodeOps branch: nothing to check."; exit 0 ;;
      esac
      body=$(jq -n --arg pr "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID" '{pullRequestURL: $pr}')
      response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
        -H "Authorization: Bearer $AICODEOPS_API_KEY" \
        -H "Content-Type: application/json" \
        -d "$body") || { echo "Release check unavailable: failing closed"; exit 1; }
      echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
      if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
        echo "AI CodeOps release gate denied this change"
        exit 1
      fi

El job se ejecuta en los pipelines de merge request. En una rama que no abrió AI CodeOps pasa sin preguntar, de modo que el pipeline sigue informando de un resultado.

Bitbucket Pipelines

Añade esto a bitbucket-pipelines.yml. El patrón codeops/** limita el paso a los pull requests de ramas de AI CodeOps:

pipelines:
  pull-requests:
    "codeops/**":
      - step:
          name: AI CodeOps release gate
          image: alpine:3.20
          script:
            - apk add --no-cache curl jq
            - |
              AICODEOPS_URL="https://console.aicodeops.dev"
              body=$(jq -n --arg pr "https://bitbucket.org/$BITBUCKET_WORKSPACE/$BITBUCKET_REPO_SLUG/pull-requests/$BITBUCKET_PR_ID" '{pullRequestURL: $pr}')
              response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
                -H "Authorization: Bearer $AICODEOPS_API_KEY" \
                -H "Content-Type: application/json" \
                -d "$body") || { echo "Release check unavailable: failing closed"; exit 1; }
              echo "$response" | jq -r '.summary, ((.reasons // [])[] | "- " + .)'
              if [ "$(echo "$response" | jq -r '.allowed')" != "true" ]; then
                echo "AI CodeOps release gate denied this change"
                exit 1
              fi

Forgejo y Gitea Actions

Guarda esto como .forgejo/workflows/aicodeops-release-gate.yml en Forgejo, o como .gitea/workflows/aicodeops-release-gate.yml en Gitea. Pon en runs-on una etiqueta que tenga alguno de tus runners:

name: AI CodeOps release gate
on:
  pull_request:
jobs:
  release-gate:
    runs-on: docker
    steps:
      - name: Ask the release gate
        env:
          AICODEOPS_API_KEY: ${{ secrets.AICODEOPS_API_KEY }}
          AICODEOPS_URL: https://console.aicodeops.dev
          PR_URL: ${{ github.server_url }}/${{ github.repository }}/pulls/${{ github.event.number }}
          BRANCH: ${{ github.head_ref }}
        run: |
          set -eu
          case "$BRANCH" in
            codeops/run-*) ;;
            *) echo "Not an AI CodeOps branch: nothing to check."; exit 0 ;;
          esac
          response=$(curl -sS --fail --retry 3 --max-time 30 -X POST "$AICODEOPS_URL/api/release/check" \
            -H "Authorization: Bearer $AICODEOPS_API_KEY" \
            -H "Content-Type: application/json" \
            -d "{\"pullRequestURL\":\"$PR_URL\"}") || { echo "Release check unavailable: failing closed"; exit 1; }
          echo "$response"
          printf '%s' "$response" | grep -Eq '"allowed"[[:space:]]*:[[:space:]]*true' || { echo "AI CodeOps release gate denied this change"; exit 1; }

Este usa grep en lugar de jq, así que el runner solo necesita curl. El patrón admite espacios alrededor de los dos puntos, de modo que lee la respuesta igual sea cual sea su formato. Imprime la respuesta entera, incluidos los motivos.

Si el job falla en un cambio que debería pasar

  • "No workflow runs found for …": la URL que envió el job no es la que AI CodeOps guardó cuando abrió el pull request. Compara la URL del log del job con el enlace al pull request que aparece en el cambio en la consola. Una barra final se ignora.
  • El job falla antes de imprimir un resumen: la clave falta o es incorrecta, o el espacio de trabajo hizo más de 60 comprobaciones en un minuto. Comprueba el nombre del secreto y que la clave no se haya eliminado.

Conviértelo en una comprobación obligatoria

Un job que falla no detiene una fusión por sí solo. Exígelo en tu proveedor de Git:

  • GitHub. En la protección de ramas o en un ruleset de tu rama predeterminada, activa Require status checks to pass before merging y añade AI CodeOps release gate. Una comprobación aparece en la lista después de haberse ejecutado una vez. En los pull requests de otras ramas el job se omite, y GitHub cuenta un job omitido como superado.
  • GitLab. En Settings → Merge requests → Merge checks, activa Pipelines must succeed. Deja Skipped pipelines are considered successful desactivado.
  • Bitbucket. En Repository settings → Branch restrictions, añade la comprobación de fusión de un número mínimo de builds correctos sin builds fallidos. Bloquear una fusión por comprobaciones de fusión sin resolver requiere el plan Premium. En Standard la comprobación avisa y la gente puede fusionar igualmente.
  • Forgejo y Gitea. En la regla de protección de rama de tu rama predeterminada, activa Enable status check y añade el job a Status check patterns. Ejecuta antes el job una vez para que aparezca su nombre.

Después restringe quién puede hacer push a las ramas codeops/*, o haz que las aprobaciones se restablezcan cuando una rama cambia. El control responde sobre el cambio de la sesión, no sobre un commit que alguien añade a la rama después.

Opciones que conviene conocer

Añade campos al cuerpo JSON para pedir más. En los jobs de arriba es la línea jq -n:

body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
OpciónPor defectoQué hace
blockingSeverityhighLa gravedad más baja de un hallazgo abierto que deniega: critical, high, medium, low o info
minCoveragePctsin definirUn mínimo de cobertura de 0 a 100. La ejecución de pruebas más reciente que indicó cobertura debe cumplirlo
blockOnInFlightfalseDenegar mientras una sesión o un build del repositorio para el cambio sigue en ejecución
blockOnBuildFailuretrueUn build del repositorio, del commit o del pull request, que falló, agotó el tiempo o se canceló deniega. Pon false para dejar fuera los builds

El mínimo de cobertura falla en cerrado. Si fijas minCoveragePct y ninguna ejecución de pruebas del cambio indicó cobertura, el control deniega: "Coverage wasn't reported, so the 80% floor can't be checked". Un mínimo que no puede comprobar no se da por superado. Fíjalo cuando el comando de pruebas de tu proyecto imprima un resumen de cobertura, por ejemplo pytest --cov o vitest run --coverage, y la página de ejecución de la sesión muestre una cifra de cobertura.

Esperar a una sesión en ejecución. Sin blockOnInFlight, un cambio con una sesión terminada puede pasar mientras otra sigue en ejecución. Con él, el control deniega hasta que todas las sesiones y todos los builds del cambio han terminado. Un job que deba esperar puede repetir la llamada con una pausa mientras un motivo diga que algo sigue en ejecución, y desistir pasado su propio límite de tiempo. Mantente por debajo de 60 comprobaciones por minuto para el espacio de trabajo.

Los flujos de trabajo obligatorios, las licencias no permitidas, un despliegue anterior obligatorio y los demás campos están en la página de la API, con cada campo de la respuesta en la referencia de la comprobación de publicación.

Siguientes pasos

Preguntas frecuentes

¿Por qué los jobs solo preguntan por las ramas codeops/?

El control juzga las sesiones de AI CodeOps y deniega un cambio que no tiene ninguna. Un pull request que una persona abrió a mano no tiene ninguna sesión detrás, así que preguntar por él fallaría siempre.

¿Un cambio denegado vuelve con un estado de error?

No. El endpoint responde 200 tanto si permite como si deniega. El job lee el campo allowed y falla salvo que sea true.

¿Qué pasa si no se puede llegar al control?

El job falla. Cada job de esta página trata un error de red, una clave incorrecta o un límite de peticiones como un fallo, de modo que una comprobación que no se ejecutó nunca da por bueno un cambio.

¿Te resultó útil esta página?