Desplegar Sitio Web
Resumen
Usa esta habilidad para guiar el despliegue de un sitio web ya generado en GitHub Pages. Se espera que el proyecto sea un sitio estático de Astro almacenado en un repositorio de GitHub, con los archivos fuente confirmados y el despliegue manejado por GitHub Actions.
Esta habilidad asume que el sitio web ya existe. No rediseñes el sitio a menos que el usuario lo solicite.
Modelo de Despliegue
Usa esta configuración para el flujo de trabajo actual del sitio web personal:
- Rastrea el código fuente con Git.
- Ignora las carpetas generadas o de dependencias como
node_modules/,dist/,.astro/ytmp/. - Compila el sitio con
npm.cmd run build. - Despliega desde GitHub Actions a GitHub Pages.
- Mantén el desarrollo local en
http://localhost:4321/. - Usa una ruta base
basede Astro solo durante las compilaciones de GitHub Actions para URLs de proyecto Pages comohttps://USERNAME.github.io/REPOSITORY/.
Antes de Desplegar
Verifica la preparación con comandos ligeros:
git status
npm.cmd run build
Confirma que existan estos archivos o configuraciones:
package.jsonastro.config.mjs.gitignore.github/workflows/deploy.ymlsrc/public/
Para este proyecto, astro.config.mjs debe soportar compilaciones locales y de GitHub Pages, por ejemplo:
import { defineConfig } from "astro/config";
const isGithubPagesBuild = process.env.GITHUB_ACTIONS === "true";
export default defineConfig({
site: "https://USERNAME.github.io",
base: isGithubPagesBuild ? "/REPOSITORY" : "/",
});
Usa ayudantes de URL en las páginas/layouts de Astro al enlazar a recursos públicos locales o páginas internas:
const base = import.meta.env.BASE_URL;
const url = (path: string) => {
const normalizedBase = base.endsWith("/") ? base : `${base}/`;
const normalizedPath = path.replace(/^\/+/g, "");
return `${normalizedBase}${normalizedPath}`;
};
Flujo de Trabajo de GitHub Actions
Usa un flujo de trabajo para Pages como este:
name: Deploy to GitHub Pages
on:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: pages
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Build with Astro
uses: withastro/action@v6
deploy:
needs: build
runs-on: ubuntu-latest
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v5
Explica las acciones de forma sencilla cuando sea necesario:
actions/checkout@v7: descarga el repositorio en el ejecutor de GitHub Actions.withastro/action@v6: instala dependencias, compila el sitio de Astro y prepara el artefacto de Pages.actions/deploy-pages@v5: publica el artefacto compilado en GitHub Pages.
El sufijo @vN fija una versión principal de la acción.
Pasos para el Repositorio y Confirmación
Guía al usuario para confirmar y enviar los cambios fuente listos para despliegue:
git status
git add .
git commit -m "Preparar despliegue del sitio web"
git push origin main
Si Git reporta advertencias de finales de línea como LF will be replaced by CRLF, explica que se trata de una advertencia de normalización de finales de línea en Windows y que normalmente no bloquea el despliegue.
Si Git reporta que no hay identidad de usuario configurada, configura la identidad del repositorio o global antes de confirmar. Si la privacidad es importante, usa el correo electrónico noreply del usuario en GitHub.
Configuración de GitHub Pages
Guía al usuario en GitHub:
- Abre el repositorio en GitHub.
- Ve a
Settings. - Ve a
Pages. - En
Build and deployment, estableceSourceenGitHub Actions. - Guarda si GitHub muestra un botón de guardar.
- Ve a la pestaña
Actionsy abre la ejecución de despliegue más reciente. - Espera hasta que el flujo de trabajo se complete correctamente.
- Abre la URL de Pages que muestra GitHub.
Para un sitio de proyecto, la URL esperada suele ser:
https://USERNAME.github.io/REPOSITORY/
Verificación
Después del despliegue, verifica:
- La página de inicio carga.
- Los enlaces de navegación funcionan.
- Las imágenes cargan.
- Los archivos descargables, como el PDF del CV, se abren correctamente.
- La URL del navegador incluye la ruta del repositorio para Pages de proyecto.
- No aparecen rutas rotas como
/REPOSITORYprojects,/REPOSITORYprofile.jpgo/REPOSITORYfile.pdfen el HTML generado.
Si el sitio desplegado está roto pero la vista previa local funciona, revisa primero el manejo de la ruta base.
Si GitHub Actions falla, inspecciona el paso que falla:
- Fallo en Checkout: problema de repositorio o permisos.
- Fallo en Install/Build: problema de dependencias, Astro o código fuente.
- Fallo en Deploy: problema de fuente/permisos/configuración de GitHub Pages.
Criterios de Finalización
Considera que la tarea de despliegue está completa cuando:
- La compilación local pasa.
- Los cambios fuente están confirmados y enviados.
- La fuente de GitHub Pages está configurada en GitHub Actions.
- La ejecución de despliegue de Actions se completa correctamente.
- La URL pública de Pages carga el sitio web correctamente.