Saltar al contenido

Despliega tu sitio de Astro en GitHub Pages

Puedes utilizar GitHub Pages para alojar un sitio web de Astro estático y prerenderizado directamente desde un repositorio en GitHub.com utilizando GitHub Actions.

Cómo desplegar

Sección titulada “Cómo desplegar”

Astro mantiene una GitHub Action oficial de Astro para desplegar tu proyecto en GitHub Pages con muy poca configuración y es la forma recomendada de realizar el despliegue en GitHub Pages.

Sigue las instrucciones a continuación para utilizar la GitHub Action para desplegar tu sitio de Astro en GitHub Pages. Esto creará un sitio web a partir de tu repositorio en una URL de GitHub (por ejemplo, https://<username>.github.io/<my-repo>). Una vez desplegado, opcionalmente puedes configurar un dominio personalizado para desplegar tu sitio de GitHub Pages en tu dominio preferido (por ejemplo, https://example.com).

  1. Crea un nuevo archivo en tu proyecto en .github/workflows/deploy.yml y pega el YAML a continuación.

    deploy.yml
    name: Deploy to GitHub Pages
    

    on:
      # Trigger the workflow every time you push to the `main` branch
      # Using a different branch name? Replace `main` with your branch’s name
      push:
        branches: [ main ]
      # Allows you to run this workflow manually from the Actions tab on GitHub.
      workflow_dispatch:
    

    # Allow this job to clone the repo and create a page deployment
    permissions:
      contents: read
      pages: write
      id-token: write
    

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v6
          - name: Install, build, and upload your site
            uses: withastro/action@v6
            # with:
              # path: . # The root location of your Astro project inside the repository. (optional)
              # node-version: 24 # The specific version of Node that should be used to build your site. Defaults to 24. (optional)
              # package-manager: pnpm@latest # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
              # build-cmd: pnpm run build # The command to run to build your site. Runs the package build script/task by default. (optional)
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Use single quotation marks for the variable value. (optional)
    

      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

    La acción de Astro se puede configurar con entradas opcionales. Proporciona estas descomentando la línea with: y la entrada que deseas utilizar.

    Si tu sitio requiere variables de entorno públicas, descomenta la línea env: y agrégalas allí. (Consulta la documentación de GitHub sobre cómo establecer secretos para agregar variables de entorno privadas).

  2. En tu archivo de configuración de Astro, establece site en la URL de GitHub de tu sitio desplegado.

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://astronaut.github.io',
    })

    El valor para site debe ser uno de los siguientes:

  3. En astro.config.mjs, configura un valor para base (normalmente requerido).

    GitHub Pages publicará tu sitio web en una dirección que depende tanto de tu nombre de usuario como del nombre de tu repositorio (por ejemplo, https://<username>.github.io/<my-repo>/). Establece un valor para base que especifique el repositorio para tu sitio web. Esto es para que Astro entienda que la raíz de tu sitio web es /my-repo, en lugar del valor predeterminado /. Puedes omitir esto si el nombre de tu repositorio coincide con el patrón especial <username>.github.io (por ejemplo, https://github.com/username/username.github.io/)

    Configura base como el nombre del repositorio comenzando con una barra diagonal (por ejemplo, /my-repo):

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://astronaut.github.io',
      base: '/my-repo',
    })

  4. En GitHub, ve a la pestaña Settings (Configuración) de tu repositorio y busca la sección Pages (Páginas) de la configuración.

  5. Elige GitHub Actions como la fuente (Source) de tu sitio.

Cuando realices un push con cambios en el repositorio de tu proyecto de Astro, la GitHub Action los desplegará automáticamente por ti en tu URL de GitHub.

Cambiar tu URL de GitHub por un dominio personalizado

Sección titulada “Cambiar tu URL de GitHub por un dominio personalizado”

Una vez que tu proyecto de Astro esté desplegado en GitHub Pages en una URL de GitHub siguiendo las instrucciones anteriores, puedes configurar un dominio personalizado. Esto significa que los usuarios pueden visitar tu sitio en tu dominio personalizado https://example.com en lugar de https://<username>.github.io.

  1. Configura el DNS para tu proveedor de dominio.

  2. Agrega un registro ./public/CNAME a tu proyecto.

    Crea el siguiente archivo en tu carpeta public/ con una sola línea de texto que especifique tu dominio personalizado:

    public/CNAME
    sub.example.com

    Esto desplegará tu sitio en tu dominio personalizado en lugar de user.github.io.

  3. En tu configuración de Astro, actualiza el valor de site con tu dominio personalizado. No establezcas un valor para base, y elimina uno si existe:

    astro.config.mjs
    import { defineConfig } from 'astro/config'
    

    export default defineConfig({
      site: 'https://example.com',
      base: '/my-repo'
    })

  4. Si es necesario, actualiza todos los enlaces internos de tus páginas para eliminar el prefijo base:

    <a href="/my-repo/about">About</a>

Ejemplos

Sección titulada “Ejemplos”

Más guías de implementación

Contribuir Comunidad Patrocinar