Déployer votre site Astro sur GitHub Pages

Vous pouvez utiliser GitHub Pages pour héberger un site Astro statique et pré-rendu directement à partir d'un dépôt sur GitHub.com en utilisant les actions de GitHub.

Comment déployer

Astro maintient une action GitHub officielle dédiée à Astro pour déployer votre projet sur GitHub Pages nécessitant très peu de configuration. Il s'agit du moyen privilégié pour déployer sur GitHub Pages.

Suivez les instructions ci-dessous pour utiliser l'action GitHub afin de déployer votre site Astro sur GitHub Pages. Cela créera un site web à partir de votre dépôt, avec une URL GitHub (par exemple, https://<nom-utilisateur>.github.io/<mon-depot>). Une fois déployé, vous pouvez éventuellement configurer un domaine personnalisé pour déployer votre site GitHub Pages sur votre domaine préféré (par exemple https://example.com).

Créez un nouveau fichier .github/workflows/deploy.yml dans votre projet et collez le YAML ci-dessous.

name: Déployer sur GitHub Pages

on:
  # Déclenchez le workflow à chaque fois que vous poussez vers la branche `main`
  # Vous utilisez un nom de branche différent ? Remplacez `main` par le nom de votre branche.
  push:
    branches: [ main ]
  # Vous permet d'exécuter ce workflow manuellement à partir de l'onglet Actions sur GitHub.
  workflow_dispatch:
  
# Autoriser cette tâche à cloner le dépôt et à créer un déploiement de page
permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Extraire votre dépôt à l'aide de git
        uses: actions/checkout@v5
      - name: Installer, compiler et télécharger votre site
        uses: withastro/action@v5
        # with:
          # path: . # L'emplacement racine de votre projet Astro dans le dépôt. (facultatif)
          # node-version: 24 # Version spécifique de Node à utiliser pour compiler votre site. La valeur par défaut est 22. (facultatif)
          # package-manager: pnpm@latest # Gestionnaire de paquets Node à utiliser pour installer les dépendances et compiler votre site. Détecté automatiquement en fonction de votre fichier de verrouillage. (facultatif)
          # build-cmd: pnpm run build # La commande à exécuter pour compiler votre site. Exécute par défaut le script/la tâche de compilation du paquet. (facultatif)
        # env:
          # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # Utilisez des guillemets simples pour la valeur de la variable. (facultatif)

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Déployer sur GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

L'action Astro peut être configurée avec des entrées facultatives. Fournissez-les en décommentant la ligne with: et l'entrée que vous souhaitez utiliser.

Si votre site nécessite des variables d'environnement publiques, décommentez la ligne env: et ajoutez-les ici. (Consultez la documentation GitHub sur la définition des secrets pour ajouter des variables d'environnement privées.)

:::cautionL'action officielle d'Astro recherche un fichier de verrouillage pour détecter votre gestionnaire de paquets préféré (npm, yarn, pnpm ou bun). Vous devez envoyer le fichier package-lock.json, yarn.lock, pnpm-lock.yaml ou bun.lockb généré automatiquement par votre gestionnaire de paquets dans votre dépôt.:::

Dans votre fichier de configuration Astro, définissez site avec l'URL GitHub de votre site déployé.
```
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
})
```
La valeur de site doit être l’une des suivantes :
- L'URL suivante reposant sur votre nom d'utilisateur : https://<username>.github.io
- L'URL aléatoire générée automatiquement pour une page privée d'une organisation GitHub : https://<chaine-de-caracteres-aleatoire>.pages.github.io/
Dans astro.config.mjs, configurez une valeur pour base (généralement requis).

GitHub Pages publiera votre site web à une adresse qui dépend à la fois de votre nom d'utilisateur et du nom de votre dépôt (par exemple, https://<nom-utilisateur>/github.io/<mon-depot>/). Définissez une valeur pour « base » qui spécifie le dépôt de votre site web. Cela permet à Astro de comprendre que la racine de votre site web est /mon-depot, plutôt que la valeur par défaut /. Vous pouvez ignorer cette étape si le nom de votre dépôt correspond au modèle spécial <nom-utilisateur>.github.io (par exemple, https://github.com/nom-utilisateur/nom-utilisateur.github.io/).

Configurez base comme nom du dépôt commençant par une barre oblique (par exemple, /mon-depot) :
```
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://astronaut.github.io',
  base: '/mon-depot',
})
```
:::caution[Liens internes quand base est configurée]Lorsque cette valeur est configurée, tous les liens internes à vos pages doivent être préfixés par la valeur de votre base :
```
<a href="/mon-depot/a-propos">À propos</a>
```
En savoir plus sur la configuration d'une valeur pour base.:::
Sur GitHub, accédez à l’onglet Paramètres de votre dépôt et recherchez la section Pages des paramètres.
Choisissez GitHub Actions comme Source de votre site.

Lorsque vous envoyez des modifications dans le dépôt de votre projet Astro, l’action GitHub les déploiera automatiquement pour vous sur votre URL GitHub.

Remplacer votre URL GitHub par un domaine personnalisé

Une fois votre projet Astro déployé sur GitHub Pages à une URL GitHub en suivant les instructions précédentes, vous pouvez configurer un domaine personnalisé. Cela signifie que les utilisateurs peuvent visiter votre site via votre domaine personnalisé https://example.com au lieu de https://<nom-utilisateur>.github.io.

Configurez le DNS pour votre fournisseur de domaine.
Ajoutez un enregistrement ./public/CNAME à votre projet.

Créez le fichier suivant dans votre dossier public/ avec une seule ligne de texte qui spécifie votre domaine personnalisé :
```
sub.example.com
```
Cela déploiera votre site sur votre domaine personnalisé au lieu de utilisateur.github.io.
Dans votre configuration Astro, remplacez la valeur de site par votre domaine personnalisé. Ne définissez pas de valeur pour base et supprimez-la si elle existe :
```
import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://example.com',
  base: '/mon-depot'
})
```
Si nécessaire, mettez à jour tous les liens internes à vos pages pour supprimer le préfixe base :
```
<a href="/mon-depot/a-propos">À propos</a>
```