# 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.

Fuente: https://aicodeops.dev/es/docs/release-gate-ci

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](https://aicodeops.dev/es/docs/quality-gates) 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 CI           | Dónde va el secreto                                                                          |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| GitHub Actions          | **Settings → Secrets and variables → Actions** del repositorio, como secreto del repositorio |
| GitLab CI               | **Settings → CI/CD → Variables**, enmascarado                                                |
| Bitbucket Pipelines     | **Repository settings → Repository variables**, con **Secured** marcado                      |
| Forgejo y Gitea Actions | **Settings → 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](https://aicodeops.dev/es/docs/api#workspace-api-keys).

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`:

```yaml
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`:

```yaml
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:

```yaml
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:

```yaml
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`:

```bash
body=$(jq -n --arg pr "$PR_URL" '{pullRequestURL: $pr, blockingSeverity: "medium", minCoveragePct: 80}')
```

| Opción                | Por defecto | Qué hace                                                                                                                                          |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `blockingSeverity`    | `high`      | La gravedad más baja de un hallazgo abierto que deniega: `critical`, `high`, `medium`, `low` o `info`                                             |
| `minCoveragePct`      | sin definir | Un mínimo de cobertura de 0 a 100. La ejecución de pruebas más reciente que indicó cobertura debe cumplirlo                                       |
| `blockOnInFlight`     | `false`     | Denegar mientras una sesión o un build del repositorio para el cambio sigue en ejecución                                                          |
| `blockOnBuildFailure` | `true`      | Un 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](https://aicodeops.dev/es/docs/api), con cada campo de la respuesta en la [referencia de la comprobación de publicación](https://aicodeops.dev/docs/api/release-check).

## Siguientes pasos

- [Controles de calidad](https://aicodeops.dev/es/docs/quality-gates)
- [API](https://aicodeops.dev/es/docs/api)
- [Aprobaciones y políticas](https://aicodeops.dev/es/docs/approvals-and-policies)
- [Despliegues controlados](https://aicodeops.dev/es/docs/gated-deploys)

## 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.
