Automatización con Woodpecker CI
Este repositorio utiliza Woodpecker CI para compilar y desplegar automáticamente la documentación en Codeberg Pages.
Workflow de Woodpecker
Cada vez que se hace un push a la rama main (o la que se ponga en when), Woodpecker ejecuta los siguientes pasos en un contenedor aislado:
- Clone: Descarga el código fuente de
main. - Build:
- Usa una imagen de
alpine:edge. - Instala
mdbook. - Compila el libro (genera la carpeta
book/con el HTML).
- Publish:
- Clona la rama
pages(donde se aloja el sitio web) en una carpeta temporal. - Copia el HTML generado (
book/) dentro de esa carpeta. - Configura git con identidad de bot.
- Hace un
commitypushde vuelta al repositorio.
Configuración (.woodpecker.yml)
El archivo de configuración se encuentra en la raíz del repositorio.
Puntos clave:
when: branch: main: Solo se activa al modificar la rama principal.image: alpine:edge: Usamos Alpine para tener un entorno ligero y rápido.[SKIP CI]: Etiqueta obligatoria en el mensaje de commit del bot para evitar que Woodpecker entre en un bucle infinito al detectar su propio push.
Secretos Requeridos
Para que el despliegue funcione, Woodpecker necesita permisos de escritura. Estos se configuran en Settings -> Secrets (del repositorio o del usuario).
| Secreto | Valor | Descripción |
|---|---|---|
codeberg_token | Token de acceso | Debe tener permisos write:repo (o Repository: Read and write). Generado en User Settings -> Applications. |
mail | Email para git | Se recomienda usar usuario@noreply.codeberg.org para mantener privacidad. |
Lógica de Seguridad
En el paso de publicación, usamos este comando defensivo:
if ! git diff --cached --quiet; then
git commit -m "chore(deploy): Woodpecker CI ${CI_BUILD_CREATED} [SKIP CI]" && git push;
fi
git diff --cached --quiet: Verifica si hubo cambios reales en el HTML generado.if ! ...: Si NO está quieto (hay cambios), procede. Si el sitio es idéntico, no hace nada (evita commits vacíos).[SKIP CI]: Le dice a Woodpecker que ignore este commit y no dispare una nueva compilación.