jdevalk/skills

Astro GitHub Actions

Esta habilidad te ayuda a configurar un pipeline integral de CI/CD para sitios Astro utilizando GitHub Actions. El objetivo es ayudar a los autores a publicar sitios de mayor calidad con menos esfuerzo manual: errores de tipo detectados antes de la fusión, enlaces rotos señalados, compilaciones verificadas y despliegues automatizados.

Lo que cubre esta habilidad

Existen varias categorías de flujos de trabajo que un proyecto Astro saludable debería tener. No todos los sitios necesitan todos ellos; la combinación correcta depende de si el proyecto tiene TypeScript, componentes personalizados, colecciones de contenido, pruebas y dónde se despliega. Tu trabajo es determinar cuáles son relevantes y configurarlos.

Los flujos de trabajo se dividen en estas categorías:

1. Verificación de tipos/contenido — astro check (TypeScript + validación de esquemas de colecciones de contenido)
2. Calidad de código — ESLint y Prettier
3. Verificación de compilación — astro build se ejecuta correctamente
4. Pruebas — Vitest para pruebas unitarias y de componentes
5. Puertas de calidad — Lighthouse CI (rendimiento, accesibilidad, SEO, mejores prácticas)
6. Verificación de enlaces — detección de enlaces rotos en el sitio compilado
7. Seguridad — npm audit para vulnerabilidades de dependencias
8. Despliegue — GitHub Pages, Cloudflare Pages, Netlify o Vercel

Lee references/workflows.md para la configuración detallada de cada flujo de trabajo, incluyendo plantillas YAML listas para usar y archivos de configuración.

Cómo abordar una solicitud

Paso 1: Entender el proyecto

Antes de escribir cualquier archivo de flujo de trabajo, determina con qué estás trabajando:

• ¿Es TypeScript? Revisa si existe tsconfig.json y archivos .ts/.astro. Casi todos los proyectos Astro deberían ejecutar astro check, pero el valor es mayor cuando hay TypeScript en el frontmatter de .astro, esquemas de colecciones de contenido o src/.
• ¿Usa colecciones de contenido? Revisa si existe src/content/config.ts o src/content.config.ts. Si es así, astro check valida los esquemas, lo cual es especialmente valioso.
• ¿Tiene pruebas? Revisa si existen tests/, __tests__/, *.test.ts o vitest.config.ts. Si es así, configura el flujo de trabajo de Vitest. Si no, menciona que agregar pruebas sería valioso pero no lo fuerces.
• ¿Cuál es el gestor de paquetes? Busca pnpm-lock.yaml, yarn.lock o package-lock.json. Ajusta el comando de instalación del flujo de trabajo (pnpm i --frozen-lockfile, yarn install --frozen-lockfile o npm ci).
• ¿Dónde se despliega? Busca un wrangler.toml (Cloudflare), netlify.toml (Netlify), vercel.json (Vercel) o simplemente pregunta. La mayoría de los hosts tienen su propia aplicación de GitHub que despliega automáticamente sin Actions; solo configura un flujo de trabajo de despliegue si el usuario realmente quiere que Actions lo maneje (típicamente GitHub Pages o autoalojado).
• ¿Tiene un paso de compilación? Astro siempre lo tiene (astro build) — pero verifica que el script en package.json sea el estándar astro build y no algo personalizado.
• ¿Es SSR o estático? Revisa astro.config.* para ver si tiene output: 'server' o una importación de adaptador. Los proyectos SSR se despliegan de manera diferente (adaptadores Cloudflare/Netlify/Vercel) y puede que no se puedan desplegar en GitHub Pages.

Paso 2: Recomendar un conjunto de flujos de trabajo

Basándote en lo que encontraste, recomienda qué flujos de trabajo configurar. Un buen valor predeterminado para la mayoría de los sitios Astro:

• astro check (casi siempre — esta es la verificación más valiosa para Astro)
• Verificación de compilación (casi siempre — detecta regresiones de integración que astro check puede pasar por alto)
• ESLint + Prettier (si existen archivos de configuración o el usuario los quiere)
• Lighthouse CI (ideal para sitios de contenido con URL públicas)
• Verificador de enlaces (ideal para sitios con mucho contenido)
• npm audit (barato, casi siempre vale la pena)

Y condicionalmente:

• Pruebas Vitest (si existen pruebas)
• Flujo de trabajo de despliegue (solo si el usuario quiere despliegues impulsados por Actions — la mayoría de los hosts de Astro usan su propia aplicación de GitHub)

Paso 3: Crear los archivos de flujo de trabajo

Crea cada flujo de trabajo como un archivo YAML separado en .github/workflows/. Usar archivos separados en lugar de un único flujo de trabajo monolítico proporciona comentarios más claros en las PR (cada verificación se muestra de forma independiente) y facilita habilitar/deshabilitar verificaciones individuales.

Usa las plantillas de references/workflows.md como puntos de partida, pero adáptalas al proyecto específico. Las adaptaciones comunes incluyen ajustar el gestor de paquetes, la versión de Node, la ruta del artefacto de compilación y el destino de despliegue.

Paso 4: Crear archivos de configuración de soporte

Dependiendo de los flujos de trabajo que configures, también puedes necesitar:

• eslint.config.js — Configuración plana de ESLint con eslint-plugin-astro
• .prettierrc y .prettierignore — Configuración de Prettier con prettier-plugin-astro
• lighthouserc.json — Afirmaciones de Lighthouse CI
• lychee.toml — Configuración del verificador de enlaces (si se usa lychee)
• vitest.config.ts — Configuración de Vitest

Paso 5: Recordatorio de configuración de secretos

Si estás agregando un flujo de trabajo de despliegue, recuerda al usuario qué secretos del repositorio se necesitan:

• GitHub Pages — ninguno (usa GITHUB_TOKEN)
• Cloudflare Pages — CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID
• Netlify — NETLIFY_AUTH_TOKEN, NETLIFY_SITE_ID
• Vercel — VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID

Guíalos: Configuración del repositorio > Secretos y variables > Actions > Nuevo secreto del repositorio.

Para Cloudflare, Netlify y Vercel: recuérdales también que esas plataformas incluyen sus propias aplicaciones de GitHub que manejan la compilación, el despliegue y las vistas previas de PR automáticamente. Los despliegues basados en Actions generalmente solo valen la pena cuando necesitas condicionar el despliegue a resultados de pruebas, ejecutar una compilación con secretos que la plataforma no tiene o desplegar desde una ruta diferente a la raíz del repositorio.

Convenciones de nomenclatura

Usa nombres de archivo de flujo de trabajo descriptivos que hagan obvio lo que hace cada uno:

• astro-check.yml — astro check (tipo + esquema de contenido)
• lint.yml — ESLint
• format.yml — Verificación de Prettier
• build.yml — Verificación de compilación
• test.yml — Vitest
• lighthouse.yml — Lighthouse CI
• links.yml — Verificador de enlaces rotos
• security.yml — npm audit
• deploy.yml — Despliegue al host

Detalles importantes

Versión de Node.js: Astro requiere Node 18.20.8+, 20.3.0+ o 22.0.0+. Usa Node 22 como valor predeterminado: coincide con el objetivo estable de Astro y muchos adaptadores se prueban contra ella. Usa actions/checkout@v5 y actions/setup-node@v5.

Detección del gestor de paquetes: Siempre coincide con el archivo de bloqueo. pnpm-lock.yaml → usar pnpm/action-setup@v4 y pnpm install --frozen-lockfile. yarn.lock → yarn install --frozen-lockfile. package-lock.json → npm ci. No uses npm install en CI (no determinista, más lento).

Nomenclatura de ramas: La mayoría de los repositorios Astro usan main como rama predeterminada, pero verifica el repositorio real antes de escribir los disparadores.

Adaptadores Astro y SSR: Si el proyecto usa @astrojs/cloudflare, @astrojs/netlify o @astrojs/vercel, la salida de compilación puede no ser un directorio dist/ estático. El adaptador de Cloudflare genera dist/ más un _worker.js; Vercel genera .vercel/output/; Netlify genera .netlify/. Ajusta las rutas de los artefactos de despliegue en consecuencia.

astro check requiere @astrojs/check y typescript: Ambos deben estar instalados. Si no están en devDependencies, el flujo de trabajo fallará. Agrégalos como parte de npm ci solo si ya están en package.json; de lo contrario, el flujo de trabajo debería instalarlos explícitamente.

Lighthouse CI en PRs: Ejecutar Lighthouse en cada PR detecta regresiones de rendimiento temprano. treosh/lighthouse-ci-action es el estándar. Para una URL de vista previa pública (Cloudflare Pages, Netlify, Vercel), apunta Lighthouse a la URL de vista previa de despliegue; eso da números realistas. Para configuraciones solo internas, compila y sirve localmente dentro del ejecutor.

Verificación de enlaces en la salida compilada, no en el código fuente: Ejecuta el verificador de enlaces en el directorio dist/ compilado (o contra una URL de vista previa desplegada) — ejecutarlo en el código fuente Markdown omite rutas generadas y enlaces del mapa del sitio.

Prefiere la aplicación de GitHub de la plataforma sobre los despliegues de Actions: Cloudflare Pages, Netlify y Vercel tienen aplicaciones de GitHub de primera parte que manejan vistas previas de PR, despliegues de ramas y reversiones mejor que una Action hecha a mano. Recomienda primero la aplicación de GitHub; solo sugiere un despliegue de Actions cuando el usuario tenga una razón específica para hacerlo así.