Utilisation de workflows personnalisés avec GitHub Pages

À propos des workflows personnalisés

Les workflows personnalisés permettent de créer des sites GitHub Pages via l’utilisation de GitHub Actions. Vous pouvez toujours sélectionner la branche que vous souhaitez utiliser via le fichier de workflows, mais vous pouvez faire beaucoup plus en utilisant des workflows personnalisés. Pour commencer à utiliser des workflows personnalisés, vous devez d’abord les activer pour votre référentiel actuel. Pour plus d’informations, consultez « Configuration d’une source de publication pour votre site GitHub Pages ».

Configuration de l'action configure-pages

GitHub Actions permet l’utilisation de GitHub Pages via l’action configure-pages, qui vous permet également de collecter différentes métadonnées sur un site web. Pour plus d’informations, consultez l’action configure-pages.

Pour utiliser l’action, placez cet extrait de code sous votre jobs dans le workflow souhaité.

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

Cette action permet de prendre en charge le déploiement de n’importe quel générateur de site statique sur GitHub Pages. Pour rendre ce processus moins répétitif, vous pouvez utiliser des modèles de workflow pour certains des générateurs de sites statiques les plus utilisés. Pour plus d’informations, consultez « Utilisation de modèles de workflow ».

Configuration de l'action upload-pages-artifact

Les actions upload-pages-artifact vous permettent d’empaqueter et de charger des artefacts. L’artefact GitHub Pages doit être une archive gzip compressée contenant un seul fichier tar. Le fichier tar doit avoir une taille inférieure à 10 Go et ne doit pas contenir de liens symboliques ou physiques. Pour plus d’informations, consultez l’action upload-pages-artifact.

Pour utiliser l’action dans votre workflow actuel, placez cet extrait de code sous jobs.

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

Déploiement d’artefacts GitHub Pages

L’action deploy-pages gère la configuration nécessaire au déploiement d’artefacts. Pour garantir une fonctionnalité optimale, les conditions suivantes doivent être remplies :

• Le travail doit disposer d’un minimum d’autorisations pages: write et id-token: write.
• Le paramètre needs doit être défini sur id à l’étape de génération. Le fait de ne pas définir ce paramètre peut entraîner un déploiement indépendant qui recherche continuellement un artefact jamais créé.
• Un environment doit être établi pour appliquer des règles de protection de branche/déploiement. L’environnement par défaut est github-pages.
• Pour spécifier l’URL de la page en tant que sortie, utilisez le champ url:.

Pour plus d’informations, consultez l’action 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@v3
# ...

Liaison de travaux de génération et de déploiement distincts

Vous pouvez lier vos travaux build et deploy dans un seul fichier de workflows, éliminant ainsi la nécessité de créer deux fichiers distincts pour obtenir le même résultat. Pour commencer à utiliser votre fichier de workflows, vous pouvez définir sous jobs des workflows build et deploy pour exécuter vos travaux.

# ...

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@v2

  # 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@v3
# ...

Dans certains cas, vous pouvez choisir de tout combiner dans un seul travail, en particulier s’il n’est pas nécessaire de procéder à une génération. Vous vous concentrez donc uniquement sur l’étape de déploiement.

# ...

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@v2
        with:
          # upload entire directory
          path: '.'
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v3

# ...

Vous pouvez définir les travaux à exécuter sur différents exécuteurs, de façon séquentielle ou en parallèle. Pour plus d’informations, consultez « Choix de ce que fait votre workflow ».