GitLab Pages con Astro — lecciones aprendidas

CI que funciona

image: node:22-alpine

pages:
  stage: deploy
  script:
    - npm ci
    - npm run build
    - mkdir -p public
    - cp -r dist/* public/
  artifacts:
    paths:
      - public
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

Por qué funciona y qué evitar

1. cp -r dist/* public/ no mv dist public

GitLab Pages requiere que public/ sea un directorio creado explícitamente. mv dist public renombra el inodo original y GitLab no lo activa correctamente → 404. Siempre: mkdir -p public && cp -r dist/* public/.

2. Un solo job autosuficiente

GitLab Pages solo activa el deploy cuando el job llamado pages genera el artifact él mismo. Separar en build + pages con artifact compartido es frágil aunque se use needs: [build]. Mantener todo en un único job pages.

3. Node 22 mínimo para Astro 5

Astro 5 depende de undici >= 8 que requiere Node >= 22.19.0. Con Node 20 se instala pero con warnings de motor incompatible y posible comportamiento inesperado. Usar siempre node:22-alpine o superior.

4. Visibilidad de Pages en repos privados

Con repo privado, Pages es privado por defecto. Para hacerlo público: Settings → General → Visibility → Pages → Everyone. La URL sigue el patrón https://<namespace-id>.gitlab.io/ (no gitlab.io/<user>/<repo>).