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-le avant de modifier la branche de production.
Dépôt GitHub compagnonStarter compagnon pour aperçus Next.jsTylorMayfield/digitalocean-nextjs-pr-previewsVoir sur GitHubCe 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.
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.
Ajoutez les secrets dans l’interface des variables d’exécution chiffrées d’App Platform. Dans Next.js, seules les variables préfixées NEXT_PUBLIC_ sont exposées au code navigateur pendant la compilation. Considérez toute autre variable comme côté serveur et ne commitez jamais un fichier .env avec une vraie valeur. Commencez avec seulement les valeurs nécessaires pour afficher une route de test non sensible.
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.
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 });
}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.
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 la première réponse
- 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.
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.
curl --fail --silent --show-error "https://YOUR_PREVIEW_HOST/health"Remplacez avant l’utilisation : YOUR_PREVIEW_HOST
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.