Déployer une app Next.js avec des aperçus de pull requests
Déployez une app Next.js depuis GitHub, créez un aperçu isolé par pull request et vérifiez sa santé ainsi que la route modifiée avant la production.
Ce que ce parcours de déploiement prouve
Un aperçu de pull request donne aux réviseurs une URL déployée pour une modification proposée avant son arrivée sur la branche de production. Cela ne rend pas un changement sûr à lui seul : tests, revue de code, migrations, contrôles d’accès et supervision restent nécessaires. Son intérêt est plus concret : quelqu’un peut vérifier la route affichée, la limite de connexion, le comportement d’un formulaire et la mise en page mobile sur le commit exact en revue.
Ce guide utilise App Platform pour un service web Next.js et GitHub Actions pour des aperçus temporaires de pull requests. Gardez les données d’aperçu jetables. Ne connectez pas un aperçu à une base de production, des clés API de production, des identifiants de paiement réels ou des données client. Un aperçu est un environnement de test, pas une copie de la production.
- Un dépôt Next.js dont la compilation réussit localement avec son lockfile.
- Un dépôt GitHub où vous pouvez ajouter des secrets Actions et des workflows de pull requests.
- Une équipe DigitalOcean pouvant créer des apps App Platform et un jeton API limité.
- Une route inoffensive, comme /health, qui renvoie un succès sans écrire de donnée ni envoyer d’e-mail.
- Une limite de coût : chaque aperçu est une app temporaire distincte ; vérifiez le tarif actuel d’App Platform et faites du nettoyage une condition de fin.
Ajouter une route de santé sûre avant d’automatiser les aperçus
Une route de santé est un petit contrat sur ce qu’est un déploiement réussi. Pour une application de contenu, elle peut seulement confirmer que le serveur répond. Si l’application dépend d’une base ou d’une API externe, distinguez un contrôle de vie d’un contrôle de disponibilité plus profond ; ne présentez pas une panne de dépendance externe comme un mauvais déploiement sans l’indiquer.
L’exemple ci-dessous ne renvoie volontairement aucun secret et ne fait aucune requête externe. Ajoutez-le dans l’App Router seulement si le projet n’a pas déjà une route équivalente. Consultez-le localement avant de configurer App Platform.
import { NextResponse } from "next/server";
export function GET() {
return NextResponse.json({ ok: true });
}Choisir la frontière de production avant de connecter GitHub
Créez d’abord l’application de production depuis la branche main dans App Platform. Sélectionnez le dépôt, son dossier source s’il est dans un monorepo et le composant de service web. Confirmez les commandes de compilation et d’exécution détectées au lieu de les accepter sans vérification. App Platform peut compiler depuis un dépôt Git et redéployer lorsque la branche choisie change ; cette commodité exige donc une frontière de branche explicite.
Next.js intègre les variables NEXT_PUBLIC_ au code du navigateur. Les autres valeurs peuvent aussi fuir si votre code les transmet aux composants client ou aux réponses API. Gardez les secrets côté serveur et vérifiez les réponses produites.
Dans l’écran source, choisissez Git repository, sélectionnez GitHub puis le dépôt qui contient votre app Next.js. S’il est absent, utilisez Edit your GitHub permissions avant de continuer. Sélectionner un dépôt permet seulement à App Platform d’inspecter le code ; cela ne crée ni app ni déploiement.
- Créez une app App Platform depuis la branche main et attendez la fin du premier déploiement.
- Ouvrez les réglages du composant et notez le nom du service, le port HTTP, les commandes de compilation et d’exécution, ainsi que l’URL de production.
- Ajoutez les variables d’exécution chiffrées dans le tableau de bord ; ne placez pas les secrets réservés à la production dans les secrets GitHub d’aperçu.
- Définissez un contrôle de santé sur une route rapide, non authentifiée et sans effet de bord. N’utilisez pas une route qui écrit un enregistrement juste pour prouver le déploiement.
Créer un aperçu par pull request
Le starter compagnon contient le spec de base .do/app.yaml, le workflow d’aperçu et le workflow de nettoyage. DigitalOcean documente une Action GitHub capable de créer une app App Platform unique par pull request et d’exposer son URL comme sortie d’Action. Enregistrez le jeton API DigitalOcean comme secret GitHub Actions. Donnez-lui seulement les droits nécessaires pour App Platform, renouvelez-le lorsque la responsabilité change et ne l’affichez jamais dans un workflow ou un journal de déploiement.
Exécutez les aperçus seulement pour les pull requests du même dépôt, sauf si vous avez conçu un workflow distinct pour les forks non fiables. Un workflow qui utilise des secrets privilégiés sur un fork peut transformer un aperçu en fuite d’identifiants. L’aperçu utilise des variables dédiées ; il doit pouvoir afficher et exercer une route de test inoffensive sans accès aux systèmes de production.
- Copiez .do/app.yaml et .github/workflows/delete-preview.yml depuis les fichiers liés vers les mêmes chemins du dépôt. Utilisez soit le workflow de déploiement ci-dessous, soit deploy-preview.yml, jamais les deux.
- Dans .do/app.yaml, remplacez github.repo par VOTRE_PROPRIETAIRE/VOTRE_DEPOT, puis choisissez région et nom d’app. Adaptez source_dir pour un monorepo, build_command au lockfile, run_command aux scripts, http_port au port écouté et health_check.http_path à /health. Vérifiez le tarif de instance_size_slug.
- Dans GitHub Settings → Secrets and variables → Actions, créez le secret de dépôt DIGITALOCEAN_APP_PLATFORM_TOKEN. Les deux workflows utilisent ce nom exact. Limitez équipe, ressources et droits aux aperçus, suppression comprise. Ne placez jamais sa valeur dans le spec.
- Commitez le spec, la route de santé et les deux workflows sur la branche par défaut avant le premier test. Adaptez le filtre branches si votre branche de production ne s’appelle pas main. Ouvrez une PR du même dépôt avec une modification visible inoffensive.
Avant de continuer : Utilisez uniquement des secrets d’aperçu et limitez ce workflow aux pull requests du même dépôt. N’exposez pas un jeton privilégié aux forks.
name: App Platform preview
on:
pull_request:
branches: [main]
permissions:
contents: read
pull-requests: write
jobs:
preview:
if: github.event.pull_request.head.repo.full_name == github.repository
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: digitalocean/app_action/deploy@v2
id: deploy
with:
deploy_pr_preview: "true"
token: ${{ secrets.DIGITALOCEAN_APP_PLATFORM_TOKEN }}
- uses: actions/github-script@v7
env:
PREVIEW_URL: ${{ fromJson(steps.deploy.outputs.app).live_url }}
with:
script: |
github.rest.issues.createComment({
issue_number: context.issue.number,
owner: context.repo.owner,
repo: context.repo.repo,
body: `Preview: ${process.env.PREVIEW_URL}`
})Vérifier l’aperçu avant la fusion
Ouvrez le lien d’aperçu depuis la pull request et vérifiez la route modifiée dans une taille mobile puis desktop. Demandez ensuite l’URL de santé. Une réponse HTTP réussie prouve que cet aperçu peut servir ce point de terminaison ; elle ne prouve pas que chaque tâche d’arrière-plan, fournisseur d’authentification, paiement ou intégration de production fonctionne.
Si l’aperçu échoue, lisez les journaux de compilation et de déploiement liés avant de modifier la configuration. Comparez les variables d’environnement de l’aperçu au minimum documenté pour cet environnement, pas à la production. Corrigez le code ou la configuration, poussez un nouveau commit et laissez la pull request créer un aperçu récent. Ne fusionnez pas parce qu’un commit précédent avait une URL.
Commencez par la première phase en échec. Une compilation en échec concerne souvent le code source, une dépendance ou la commande de compilation ; un aperçu déployé qui échoue sur /health concerne le port du service, le chemin de santé ou une variable d’exécution. Modifiez une seule limite à la fois et relancez la même pull request. N’ajoutez pas un secret de production uniquement pour faire réussir l’aperçu : un aperçu qui passe avec une mauvaise limite de données échoue toujours au contrôle de sécurité.
curl --fail --silent --show-error "https://YOUR_PREVIEW_HOST/health"Supprimer les aperçus et garder une production intentionnelle
Ajoutez le workflow de nettoyage compagnon de la documentation DigitalOcean afin que l’aperçu soit supprimé après la fermeture de la pull request. Vérifiez sa première exécution dans le tableau de bord App Platform. Laisser les aperçus en vie crée des URL ambiguës, un coût inutile et une surface croissante pour les anciennes dépendances.
Le déploiement de production reste une décision distincte : fusionnez seulement lorsque le résultat de l’aperçu, la revue et les contrôles requis sont satisfaisants. Après le déploiement, vérifiez la route de santé de production et le parcours utilisateur modifié. Si une version révèle un problème, stoppez les modifications suivantes, préservez les preuves et appliquez la procédure de récupération normale du projet au lieu de traiter un aperçu comme un mécanisme de retour arrière.
- Fermez la PR de test sans fusion. Ouvrez son exécution Actions Delete App Platform preview et vérifiez sa réussite.
- Dans App Platform, confirmez la disparition de l’app temporaire et la présence de la production. En cas d’échec, vérifiez les droits du jeton et l’identité de l’app. Supprimez manuellement cet aperçu uniquement, puis réparez le nettoyage avant d’ouvrir d’autres PR.
Vérifier le résultat
- Résultat attendu
- La pull request reçoit une URL d’aperçu, la route modifiée y est affichée et le point /health répond avec succès sans écrire de donnée.
- Arrêter si
- Arrêtez si un aperçu a des identifiants de production ou des données client, si un fork peut recevoir le jeton, si la route de santé change un état ou si les journaux révèlent un secret.
- Étape suivante
- Revoyez l’aperçu sur desktop et mobile, fusionnez seulement après les contrôles requis et confirmez que le workflow de nettoyage supprime l’app temporaire quand la pull request se ferme.