Revisa merge requests de GitLab con Codex

Usa la revisión de código de Codex para que tus merge requests de GitLab reciban una revisión adicional centrada en los problemas importantes. Codex revisa los cambios del merge request, sigue las indicaciones de tu repositorio y publica una revisión de código estándar de GitLab que se centra en los problemas graves.

La integración de revisión de código con GitLab está en versión beta y está disponible en todos los planes de ChatGPT. Se ejecuta en Codex Cloud. Esta versión beta no incluye los controles de repositorio que ofrece la aplicación de escritorio para GitHub, como Crear pull request.

Si GitLab aparece en el selector de repositorios cuando creas un entorno en la nube, selecciona un proyecto de GitLab.com al que tenga acceso tu cuenta conectada. Para las tareas y revisiones que se inicien desde GitLab, configura los webhooks como se indica más adelante.

Antes de empezar

Asegúrate de tener lo siguiente:

• Una cuenta de GitLab conectada. Para GitLab.com, sigue el proceso de conexión estándar. Para las instancias autogestionadas de GitLab o de GitLab Dedicated, el administrador del Espacio de trabajo debe configurar una plantilla.
• Un archivo AGENTS.md si quieres que Codex siga las indicaciones de revisión específicas del repositorio.

Configurar la revisión de código de Codex

Configurar la conexión con GitLab y la cuenta que usa Codex para las revisiones

Para GitLab.com, conecta tu cuenta de GitLab en Codex después de conectarte a GitLab en ChatGPT. Si usas GitLab autogestionado o GitLab Dedicated, cada revisor debe conectar su cuenta después de que se publique la plantilla del administrador del Espacio de trabajo.

Si usas GitLab autogestionado o GitLab Dedicated, abre Codex Cloud → Configuración → Conectores. Un administrador del Espacio de trabajo puede permitir que Codex cree una cuenta de servicio o guardar el token de acceso personal de una cuenta de servicio existente.

Dejar que Codex cree la cuenta

En Codex Cloud → Configuración → Conectores, selecciona la aplicación correspondiente al host de tu instancia autogestionada de GitLab o de GitLab Dedicated. Luego selecciona Configurar cuenta de servicio → Crear una cuenta de servicio. El administrador del Espacio de trabajo que complete la configuración debe tener acceso de administrador a la instancia de GitLab. Elige Grupos seleccionados o Solo proyectos seleccionados, selecciona dónde debe operar Codex y crea la cuenta. La primera opción otorga a la cuenta el rol Developer en cada grupo seleccionado. La cuenta hereda ese rol en los proyectos y subgrupos de cada grupo. La segunda opción otorga el rol Developer solo en los proyectos que elijas. Codex creará la cuenta de servicio de la instancia, llamada ChatGPT Codex Connector, con un token de acceso personal con el alcance api.

Usar una cuenta existente

En GitLab, crea o elige una cuenta de servicio y asígnale el rol Developer solo en los grupos o proyectos donde deba operar Codex. En la página Cuentas de servicio, selecciona la cuenta y luego Administrar tokens de acceso → Agregar nuevo token para crear un token de acceso personal con el alcance api y una vigencia de al menos 30 días. Vuelve a Codex, elige Usar una cuenta de servicio existente, pega el token y selecciona Guardar token. El token se cifra al guardarlo y no vuelve a mostrarse.

Administrar el token de la cuenta de servicio

Los administradores del Espacio de trabajo pueden administrar la cuenta de servicio en Codex Cloud → Configuración → Conectores. Si Codex creó la cuenta, pueden revocar el token actual y generar uno nuevo. Si se usa una cuenta existente, pueden reemplazar o eliminar el token guardado en Codex y, si es necesario, revocarlo por separado en GitLab. Codex no puede responder a la actividad de GitLab hasta que se configure un token válido.

Elegir cómo recibe Codex la actividad de GitLab

Crear un entorno de proyecto para tareas de programación o configuraciones específicas del proyecto

En Codex Cloud → Configuración → Entornos, elige el proyecto de GitLab y crea un entorno de proyecto si quieres que Codex escriba o ejecute código para ese proyecto. Por ejemplo, puede editar archivos, hacer commits o enviar cambios a la rama de un merge request. Crea también un entorno si una revisión depende de secretos, acceso a la red o comandos de configuración específicos del proyecto.

En GitLab.com también necesitas un entorno de proyecto para activar las revisiones de Codex.

Al crear el entorno, activa Habilitar la actividad de Codex desde GitLab para instalar el webhook del proyecto que envía a Codex los eventos de merge requests, comentarios e incidencias. Para crear el webhook, necesitas el rol Maintainer u Owner, acceso de administrador o un rol personalizado con permisos para administrar los webhooks del proyecto. Los webhooks firmados de proyectos y grupos requieren GitLab 19.0 o posterior. En GitLab 19.0 autogestionado, verifica que la opción webhook_signing_token esté activada. Está activada de forma predeterminada en esa versión y se eliminó en GitLab 19.1.

Habilitar la actividad para que Codex revise los proyectos de un grupo de GitLab

En GitLab autogestionado o GitLab Dedicated, los administradores del Espacio de trabajo pueden abrir Entornos → Actividad de GitLab → Administrar grupos para activar las revisiones de Codex en un grupo y sus subgrupos. Codex instalará un webhook de grupo que abarcará todos los proyectos del grupo. El usuario de GitLab conectado debe tener el rol Owner en el grupo. Los webhooks de grupo requieren GitLab Premium o Ultimate y la versión 19.0 o posterior de GitLab.

Habilitar la actividad del grupo permite revisar código, pero no crea entornos de proyecto. Para ejecutar tareas de programación iniciadas desde GitLab, como editar archivos, ejecutar comandos, hacer commits o enviar cambios a un merge request, crea un entorno de proyecto.

Configurar políticas de revisión de código

Configura las políticas de revisión de código en la configuración de revisiones de Codex. Elige tu repositorio y activa Revisión automática en Revisar código. En Revisión, elige de quiénes se revisarán los merge requests. En Activador, elige cuándo se ejecutarán las revisiones. La configuración del repositorio puede prevalecer sobre tu configuración personal predeterminada.

Solicitar una revisión de Codex

1. Menciona @codex review en un comentario del merge request.
2. Espera a que Codex reaccione (👀) y publique una revisión.

Codex publica hilos de discusión y notas de GitLab en el merge request, como lo haría alguien de tu equipo. De forma predeterminada, las revisiones solicitadas manualmente pueden incluir problemas de prioridad P0, P1 y P2, mientras que las revisiones automáticas se centran en los de prioridad P0 y P1.

Activar las revisiones automáticas

Para revisar automáticamente los merge requests que cumplan los criterios, activa Revisiones automáticas en la configuración de Codex, elige la política del repositorio de GitLab y selecciona un activador: Al abrir el MR, Con cada push o Activador inteligente (experimental). Codex ejecuta la revisión sin necesidad de un comentario con @codex review cuando el evento del merge request coincide con la política y el activador elegidos.

La actividad de GitLab debe estar habilitada mediante un webhook del proyecto o de un grupo superior. En GitLab autogestionado o GitLab Dedicated, la cuenta de servicio configurada también debe tener permisos de escritura en el proyecto. Si hay un entorno de proyecto configurado, Codex lo usa. Si la actividad ya está habilitada en un grupo superior, también queda habilitada en los proyectos que dependen de ese grupo.

Personalizar qué revisa Codex

Codex busca archivos AGENTS.md en tu repositorio y sigue las reglas de revisión de código que correspondan. Agrega una sección ## Code Review Rules al archivo más cercano al código al que se aplican las reglas. Usa encabezados ### para agrupar comprobaciones relacionadas cuando resulte útil.

Por ejemplo, un servicio que genera informes de experimentos puede evitar que el comportamiento posterior a la exposición altere la composición de una cohorte de comparación:

## Code Review Rules

### Cohortes de experimentos

- Al comparar tratamientos, no filtres por comportamientos posteriores a la exposición, como la conversión o la retención.
  Para hacerlo de forma segura, define las cohortes a partir de la asignación o la exposición e informa la conversión como resultado.

Coloca las reglas que se aplican a todo el repositorio en el archivo AGENTS.md de la raíz y las reglas específicas de un servicio en un archivo de un subdirectorio, como services/experiment_reporting/AGENTS.md. Para cada archivo modificado, Codex aplica las indicaciones de la raíz y las indicaciones más específicas que le correspondan. Así, los cambios ajenos al servicio no necesitan incluir contexto específico de ese servicio.

Empieza con dos o tres reglas concisas que recojan las comprobaciones que los revisores suelen explicar. Para redactar reglas útiles:

• Céntrate en comportamientos propios del repositorio que tengan consecuencias importantes. Describe qué restricción de compatibilidad, límite en el uso de los datos o efecto secundario inseguro se debe señalar y por qué es importante.
• Indica cómo proceder de forma segura o cuándo se aplica una excepción. Dale a Codex suficiente contexto para distinguir un problema real de un comportamiento esperado.
• Delimita el alcance de las reglas y procura que sigan vigentes. Describe los resultados esperados en vez de usar nombres de funciones que podrían cambiar. Coloca las indicaciones cerca del código al que se aplican.
• Deja las comprobaciones mecánicas en CI. Excluye de las reglas de revisión las comprobaciones de formato, el lint y otras verificaciones deterministas.

Abre un merge request representativo y solicita una revisión con @codex review. Ajusta las reglas en función de los problemas detectados y los comentarios que recibas. Limita el alcance de las indicaciones que generen comentarios irrelevantes o elimínalas.

Las reglas de revisión de código orientan a Codex. No sustituyen las pruebas, las protecciones de ramas ni las aprobaciones obligatorias.

Si quieres que una revisión en particular se centre en un tema, indícalo en el comentario del merge request:

@codex review busca problemas en la migración de la base de datos

Corregir los problemas detectados en la revisión

Para corregir los problemas detectados, Codex necesita un entorno de proyecto configurado. La actividad de grupo por sí sola permite realizar revisiones, pero no ejecutar tareas de programación. Si el proyecto tiene un entorno, deja otro comentario en el mismo merge request para pedirle a Codex que corrija un problema:

@codex corrige el problema de prioridad P1

Codex inicia un chat en la nube de la versión anterior con el merge request como contexto y puede enviar la corrección a la rama si tiene los permisos necesarios.

Asignar otras tareas a Codex

Las demás tareas de programación también requieren un entorno de proyecto configurado. La actividad de grupo por sí sola permite realizar revisiones. Si mencionas @codex en un comentario con una instrucción distinta de review, Codex inicia un chat en la nube de la versión anterior y usa tu merge request como contexto.

@codex corrige los fallos de CI

Solucionar problemas con la revisión de código

Si Codex no reacciona o no publica una revisión:

• Comprueba que esté seleccionada la aplicación de GitLab correcta. Si usas una configuración específica del proyecto, comprueba que el proyecto tenga el entorno de Codex Cloud que quieres usar.
• Comprueba que la actividad esté habilitada para el proyecto o un grupo superior. En GitLab, abre Webhooks → Eventos recientes y verifica que los eventos de merge requests y notas se entreguen correctamente.
• Si usas GitLab autogestionado o GitLab Dedicated, comprueba que el webhook del proyecto o del grupo esté firmado, que la verificación SSL esté activada y que la instancia use GitLab 19.0 o posterior. En GitLab 19.0 autogestionado, comprueba que la opción webhook_signing_token esté activada. Repara los webhooks que se hayan desactivado automáticamente tras fallar.
• Si usas GitLab autogestionado o GitLab Dedicated con una cuenta de servicio existente, comprueba que su token de acceso personal esté activo y tenga el alcance api. Si Codex creó la cuenta de servicio, verifica que esté configurada correctamente en la configuración de conectores de Codex y que el proyecto o el grupo esté habilitado.
• Si usas GitLab autogestionado o GitLab Dedicated, comprueba que la cuenta de servicio del Espacio de trabajo tenga el rol Developer en el proyecto o en un grupo superior para que Codex pueda publicar revisiones y reacciones. No basta con que el usuario de GitLab conectado tenga ese rol. La pertenencia al grupo se hereda. La actividad y el acceso de la cuenta de servicio se configuran por separado.
• Comprueba que esté activada la opción Revisión de código o Revisiones automáticas y que el MR cumpla los criterios de la política del repositorio y del activador.
• Usa @codex review.