Uso de flujos de trabajo personalizados con GitHub Pages

Puedes sacar partido al uso de GitHub Actions y GitHub Pages si creas un archivo de flujo de trabajo o eliges uno de los flujos de trabajo predefinidos.

¿Quién puede utilizar esta característica?

GitHub Pages is available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. For more information, see GitHub’s plans.

GitHub Pages now uses GitHub Actions to execute the Jekyll build. When using a branch as the source of your build, GitHub Actions must be enabled in your repository if you want to use the built-in Jekyll workflow. Alternatively, if GitHub Actions is unavailable or disabled, adding a .nojekyll file to the root of your source branch will bypass the Jekyll build process and deploy the content directly. For more information on enabling GitHub Actions, see Managing GitHub Actions settings for a repository.

En este artículo

Acerca de los flujos de trabajo personalizados

Los flujos de trabajo personalizados permiten crear sitios de GitHub Pages mediante el uso de GitHub Actions. Puedes seleccionar igualmente la rama que quieres usar mediante el archivo de flujo de trabajo, pero con los flujos de trabajo personalizados podrás hacer mucho más. Para empezar a usar flujos de trabajo personalizados, primero debes habilitarlos para el repositorio actual. Para más información, consulta Configurar una fuente de publicación para tu sitio de Páginas de GitHub.

Configuración de la acción configure-pages

Con GitHub Actions, es posible usar GitHub Pages en la acción configure-pages, lo que también permite recopilar metadatos diferentes sobre un sitio web. Para más información, vea la acción configure-pages.

Para usar la acción, coloca este fragmento de código bajo jobs en el flujo de trabajo deseado.

- name: Configure GitHub Pages
  uses: actions/configure-pages@v5

Esta acción permite que se admita la implementación desde cualquier generador de sitios estáticos en GitHub Pages. Para que este proceso sea menos repetitivo, puede usar plantillas de flujo de trabajo para algunos de los generadores de sitios estáticos más utilizados. Para más información, consulta Uso de plantillas de flujo de trabajo.

Configuración de la acción upload-pages-artifact

La acción upload-pages-artifact permite empaquetar y cargar artefactos. El artefacto GitHub Pages debe ser un archivo gzip comprimido que contenga un solo archivo tar. El archivo tar debe tener menos de 10 GB de tamaño y no debe contener ningún vínculo simbólico o físico. Para más información, vea la acción upload-pages-artifact.

Para usar la acción en el flujo de trabajo actual, coloca este fragmento de código bajo jobs.

- name: Upload GitHub Pages artifact
  uses: actions/upload-pages-artifact@v3

Implementación de artefactos de GitHub Pages

La acción deploy-pages controla la configuración necesaria para implementar artefactos. Para garantizar una funcionamiento correcto, es necesario cumplir los requisitos siguientes:

  • El trabajo debe tener como mínimo permisos pages: write y id-token: write.
  • El parámetro needs debe establecerse en el id del paso de compilación. Si no se establece este parámetro, podría producirse una implementación independiente que busque continuamente un artefacto que no se ha creado.
  • Es necesario establecer un valor de environment para aplicar reglas de protección de rama o implementación. El entorno predeterminado es github-pages.
  • Para especificar la dirección URL de la página como salida, usa el campo url:.

Para más información, vea la acción deploy-pages.

# ...

jobs:
  deploy:
    permissions:
      contents: read
      pages: write
      id-token: write
    runs-on: ubuntu-latest
    needs: jekyll-build
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    steps:
      - name: Deploy artifact
        id: deployment
        uses: actions/deploy-pages@v4
# ...

Vinculación de trabajos independientes de compilación e implementación

Puedes vincular los trabajos build y deploy en un solo archivo de flujo de trabajo, lo que elimina la necesidad de crear dos archivos independientes para obtener el mismo resultado. Para empezar a trabajar en el archivo de flujo de trabajo, puedes definir bajo jobs un trabajo build y deploy para ejecutar los trabajos.

# ...

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5
      - name: Build with Jekyll
        uses: actions/jekyll-build-pages@v1
        with:
          source: ./
          destination: ./_site
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
# ...

En algunos casos, puedes optar por combinarlo todo en un solo trabajo, sobre todo si no se requiere un proceso de compilación. En tal caso, solo te centrarías en el paso de implementación.

# ...

jobs:
  # Single deploy job no building
  deploy:
    environment:
      name: github-pages
      url: ${{steps.deployment.outputs.page_url}}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Setup Pages
        uses: actions/configure-pages@v5
      - name: Upload Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

# ...

Puedes establecer que los trabajos se ejecuten en ejecutores diferentes, secuencialmente o en paralelo. Para más información, consulta Elección de lo que hace el flujo de trabajo.