15 Pull requests y builds confiables
Quarto, publicación reproducible, agentes de programación, Markdown, Python, EPUB, análisis de datos, k-means
El Capítulo 3 revisó el cambio de un agente como un pull request y lo reconstruyó a mano desde un clon nuevo. Esa última revisión es la que quien revisa omite con más frecuencia, porque toma tiempo y una máquina limpia, y es la que el resumen fluido de un agente no puede reemplazar. La integración continua, CI, la vuelve automática: en cada pull request, una máquina que nunca ha visto el proyecto lo clona, instala las herramientas, calcula los resultados, ejecuta las pruebas y renderiza cada página, y el pull request muestra una marca verde o una cruz roja. Una guarda que los resultados ya no sostienen la pone en rojo, y nombra la oración.
Este capítulo agrega eso al proyecto Acme, con las reglas que un equipo necesita para los cambios de sus agentes: un cambio por pull request, nada generado en los commits, y nada se da por terminado hasta que se haya reconstruido. Luego publica el sitio desde main y renderiza los informes mensuales según un calendario, ambas cosas con el mismo build.
- Escribir las reglas que siguen los agentes de un equipo, y una plantilla de pull request que le sirva a quien revisa.
- Pedir un workflow de CI que ejecute los propios comandos de reconstrucción del proyecto, con las versiones fijadas a partir de sus fuentes.
- Leer un build en rojo: qué paso falló, y qué oración o prueba nombra.
- Publicar un sitio y renderizar informes periódicos desde CI, y decir cuánto cuesta cada cosa en los planes de GitHub.
15.1 De qué está hecha la CI
| Pide | GitHub Actions lo llama | Revisa |
|---|---|---|
| un build, por escrito | un workflow, un archivo YAML en .github/workflows/ |
aparece en la pestaña Actions del repositorio |
| cuándo se ejecuta | on: un disparador: pull_request, push, schedule, workflow_dispatch (a pedido) |
una ejecución empieza cuando ocurre el evento |
| una máquina limpia | un runner, runs-on: ubuntu-24.04 |
el registro muestra cómo lo instala todo |
| una cosa que hace | un paso: una acción (uses:) o un comando (run:) |
cada paso sale en verde o en rojo en el registro |
| un resultado en el pull request | un status check | una marca o una cruz junto al commit |
| un archivo que hizo la ejecución, guardado | un artefacto | una descarga al pie de la página de la ejecución |
“nada llega a main sin su build” |
una rama protegida con una comprobación obligatoria | el botón de merge espera la marca |
Un workflow debería ejecutar los comandos que ejecutas tú, no otros nuevos. El AGENTS.md del proyecto ya enumera su reconstrucción: calcular los resultados, ejecutar las pruebas, renderizar el sitio, revisar las páginas. La CI ejecuta esos mismos cuatro, así que una marca verde significa lo que siempre quiso decir “se construye en mi máquina”.
15.2 Reglas para un equipo
Los agentes de un equipo necesitan reglas que una persona sin equipo puede llevar en la cabeza. Cada sesión de un agente empieza de cero, lee AGENTS.md y hace lo que dice, así que las reglas van ahí; cada revisor o revisora abre un pull request, así que la lista de revisión va en su plantilla.
Agrega a AGENTS.md una sección "Team rules" para trabajar en equipo: trabajar en una rama, nunca hacer push a `main` ni merge; un cambio coherente por pull request; nunca hacer commit de outputs/, reports/, _site/ ni de archivos renderizados; antes de decir que un cambio está terminado, ejecutar los cuatro comandos de reconstrucción (evaluate, pruebas, render, check_site) y decir cuáles pasaron; nunca debilitar una prueba ni una guarda `claim` para que un paso pase; informar lo que no se pudo verificar. Luego crea .github/pull_request_template.md: las tres revisiones (alcance, corrección, reconstrucción) como lista de verificación, diciendo qué mirar en cada una en este proyecto, y una línea que pregunte qué agente hizo el cambio y qué no verificó. Escribe los dos en inglés, como el resto del proyecto. Hazlo en una rama nueva `team-rules` y haz commit.git switch -c team-rules · edita AGENTS.md · escribe .github/pull_request_template.md · git commit
Lee el diff como quien revisa un reglamento. Cada regla debería nombrar los archivos y los comandos de este proyecto, no buenas prácticas generales: “nunca hagas commit de outputs/” es una regla que un agente puede comprobar; “mantén limpio el repositorio”, no. La regla contra debilitar una guarda es la que más importa. Un agente al que se le pide que un paso que falla pase tiene dos caminos, corregir la oración o aflojar su guarda, y solo uno es el correcto.
15.3 Un build en cada pull request
Crea .github/workflows/check.yml: en cada pull request y en cada push a `main`, en `ubuntu-24.04` con permisos de solo lectura, instala Quarto 1.10.20 y uv 0.11.32 con su caché activado, y luego ejecuta en orden los cuatro comandos de reconstrucción de AGENTS.md. Fija cada acción a su última versión, al tag de versión mayor donde lo tenga, buscando las versiones en lugar de recordarlas, y dime qué elegiste y dónde lo comprobaste. Haz commit en una rama nueva `ci` a partir de `team-rules`.Los workflows terminados fijan actions/checkout@v7, actions/deploy-pages@v5, actions/upload-artifact@v7, actions/upload-pages-artifact@v5, astral-sh/setup-uv@v10.3.3 y quarto-dev/quarto-actions/setup@v2, las últimas versiones al 2026-11-18, y Quarto 1.10.20. Pide que se busquen las versiones: lo que un agente recuerda de la versión de una acción es tan viejo como su entrenamiento, y una versión mayor vieja puede dejar de funcionar cuando GitHub retira aquello sobre lo que se ejecuta. Nombra también las versiones de las herramientas: en la prueba, una primera versión de este prompt que solo decía “uv” obtuvo el uv más nuevo de ese día, dos versiones menores por delante de aquella con la que se construyó el proyecto. Funcionó, pero un build que instala lo más nuevo que haya no es el mismo build el mes siguiente.
git push -u origin team-rules
gh pr create --base main --fill
gh pr merge team-rules --merge
git push -u origin ci
gh pr create --base main --fillRevisa el primer pull request con las tres revisiones de su propia plantilla antes de hacer merge. Haz merge con un commit de merge, --merge, como arriba: ci parte de team-rules, así que, una vez que team-rules está en main sin cambios, el segundo pull request muestra solo el workflow, un solo cambio, como piden las reglas. (Hacer squash del primero reescribiría sus commits, y el segundo los volvería a traer.) El segundo pull request ejecuta la comprobación; su pestaña Checks muestra cada paso mientras se ejecuta. La primera ejecución descarga Quarto y todos los paquetes, lo que toma unos minutos; las siguientes restauran las descargas de uv desde un caché. Haz merge cuando la comprobación esté en verde.
Lo que cuesta: los runners estándar de GitHub Actions son gratuitos en los repositorios públicos, y los repositorios privados de una cuenta gratuita reciben 12 dólares estadounidenses de cómputo al mes (consultado el 2026-11-18; el Apéndice K). La comprobación de un repositorio privado usa esa cuota; la de uno público, no.
15.4 Un build en rojo
Una comprobación que nunca ha fallado no se ha probado. Rompe una guarda a propósito, en una rama que vas a descartar:
Esto rompe una guarda a propósito, para ver fallar la CI. En una rama nueva `try-red` a partir de `ci`, cambia la condición de una guarda `claim` en index.qmd para que deje de cumplirse, sin cambiar su oración, haz commit y dime qué oración debería nombrar la CI.git push -u origin try-red
gh pr create --base main --fill --draftLa comprobación se pone en rojo en su paso de renderizado, y el registro nombra la oración: en la prueba, “ClaimError: The results no longer support this sentence” (los resultados ya no respaldan esta oración), seguido de la oración de la página de inicio sobre la mejor versión del modelo. Eso es lo que ve alguien del equipo cuando un cambio en los datos o en el modelo vuelve falsa una afirmación escrita a mano: no un informe que dice en silencio algo equivocado, sino un pull request al que no se le puede hacer merge con ella. Cierra el pull request y borra la rama (gh pr close --delete-branch).
Para que ese “no se puede hacer merge” sea literal, protege main: en Settings del repositorio, agrega una regla de protección de rama, o un ruleset, que exija un pull request y el trabajo Check antes del merge. Un límite: en una cuenta gratuita de GitHub, las ramas protegidas y los rulesets funcionan solo en repositorios públicos; los privados necesitan GitHub Pro, Team o Enterprise (consultado el 2026-11-18). En un repositorio privado gratuito la comprobación se ejecuta igual y se muestra en rojo igual; es la regla del equipo, no la de GitHub, la que impide hacer merge de algo en rojo.
15.5 Publicar desde main
Crea .github/workflows/publish.yml: en cada push a `main`, y a pedido, ejecuta el mismo build y luego despliega _site/ en GitHub Pages con las acciones de Pages del propio GitHub (sin rama `gh-pages`), con los permisos y el entorno que necesitan, dados solo al trabajo que despliega. Dime la única configuración del repositorio que debo cambiar antes de la primera ejecución.La configuración es el origen de Pages: Settings, Pages, Build and deployment, Source: GitHub Actions. Pon en el site-url del proyecto la dirección que te da, para que funcionen las tarjetas para redes sociales del Capítulo 12. Una página cuya guarda falla nunca se publica, porque la publicación ejecuta primero el mismo build. El permiso para desplegar le pertenece solo al trabajo de despliegue: en la prueba, una versión del prompt que no lo decía se lo dio a todo el workflow, build incluido.
Primero va dónde puede publicarse (la Sección 12.6): una cuenta gratuita de GitHub publica Pages solo desde repositorios públicos; los repositorios privados necesitan un plan de pago, y un sitio que solo tu organización pueda ver necesita GitHub Enterprise Cloud (consultado el 2026-11-18). La evaluación de Acme es de datos públicos y podría ser pública; la evaluación de un cliente no podría, y publicarla necesita un servicio de alojamiento que tu organización apruebe, o ningún sitio, solo los PDF.
15.6 Informes según un calendario
Crea .github/workflows/monthly.yml: el día 2 de cada mes a las 06:17 UTC, y a pedido, ejecuta el mismo build, luego `uv run python scripts/render_params.py --formats pdf`, guarda reports/ como un artefacto descargable durante 90 días, fallando si está vacío, y ejecuta scripts/check_refs.py al final. Explica la línea del calendario en un comentario, incluida su zona horaria y por qué el minuto no es 0.El calendario terminado es la línea cron “17 6 2 * *”: minuto 17, hora 6, día 2 de cada mes. GitHub la lee en UTC, a menos que una línea timezone: a su lado nombre otra zona, como timezone: "Europe/London"; se ejecuta sobre el último commit de main, y puede empezar tarde, o en el peor caso no empezar, cuando Actions está ocupado, como lo está al comienzo de cada hora; de ahí el minuto 17, y no 0 (todo consultado el 2026-11-18). Los PDF aparecen como un artefacto al pie de la página de la ejecución, guardados durante 90 días. La revisión de referencias va al final porque necesita la red y puede fallar por razones ajenas al proyecto; al ir al final, hace fallar la ejecución sin perder los informes. Run workflow, en la página del workflow dentro de Actions, lo ejecuta en el momento, que es como probarlo sin esperar un mes.
Revisa toda aritmética de horas que escriba un agente. En la prueba, un primer comentario decía que las 06:00 UTC eran las 07:00 en Londres en invierno; son las 06:00, y las 07:00 en verano. El agente se dio cuenta, y quien lea un comentario por encima podría no hacerlo. Además, GitHub desactiva los workflows programados de un repositorio público tras sesenta días sin actividad (consultado el 2026-11-18). Un informe mensual que importa necesita a alguien que note cuándo no llega.
Lo que no se probó
El workflow de comprobación se ejecutó localmente con act, en Docker, primero en verde y luego en rojo, como arriba. El push, los pull requests, las ejecuciones de Publish y Monthly reports, el caché de uv y la protección de rama necesitan un repositorio de GitHub y no se ejecutaron para esta edición; las acciones y las configuraciones que usan se contrastaron con la documentación de GitHub el 2026-11-18. Los prompts se probaron en su versión en inglés.
¿Dos minutos sin avanzar? Pega esto en tu agente. Respalda tu trabajo y lleva el proyecto hasta este punto; luego sigue leyendo desde aquí.
Catch me up: follow ../quarto-workshop/checkpoints/20-eval-ci/README.mdResumen
- Las reglas para los agentes van en
AGENTS.md, que lee cada sesión; la lista de revisión va en la plantilla del pull request, que ve cada revisor o revisora. - La CI ejecuta los propios comandos de reconstrucción del proyecto en una máquina limpia en cada pull request, así que una marca verde significa que se construye en cualquier parte.
- Rompe una guarda a propósito una vez: una comprobación que nunca ha fallado no se ha probado.
- La publicación y los informes programados ejecutan primero el mismo build, así que no sale nada sin revisar.
- Fija las acciones a versiones buscadas en su fuente, y averigua cuánto cuesta cada paso en tu plan.
Lecturas adicionales
- GitHub, sintaxis de los workflows, eventos que disparan workflows y workflows personalizados para Pages (consultados el 2026-11-18).
- GitHub, acerca de las ramas protegidas (consultado el 2026-11-18).
- Quarto, GitHub Actions (consultado el 2026-11-18).
- nektos, act, para ejecutar un workflow en tu propia computadora (consultado el 2026-11-18).