Déploiements Git de Pages

Connectez et restreignez d’abord le dépôt à l’aide de Hébergement Git. L’accès du connecteur, les permissions de déploiement Pages et la permission de consulter l’historique des builds sont des vérifications distinctes.

Un déploiement Git de Pages transforme une révision sélectionnée d’un dépôt en un nouveau Deployment immuable de site statique. La source Git et le Build Worker produisent l’artefact ; le projet Pages détient l’historique des déploiements publiés ; les tags et les Routes contrôlent le moment où cet artefact atteint les utilisateurs.

Décidez si un build réussi crée seulement un candidat à examiner ou déplace aussi automatiquement un tag de publication. Gardez la publication manuelle tant que l’aperçu, la vérification et le retour arrière ne fonctionnent pas pour le site. Un build au vert prouve qu’un artefact a été produit ; il ne prouve pas que le domaine public, la Route TLS ou le comportement d’exécution côté client sont corrects.

Les builds Pages adossés à Git nécessitent un plan Business ou Enterprise. Les téléversements statiques manuels fonctionnent à partir de Personal. Les deux utilisent les mêmes Deployments immuables ; la vérification, la publication et le retour arrière fonctionnent donc de la même manière.

Avant de commencer

Connectez une intégration Git prise en charge et choisissez un dépôt et une branche que l’intégration est autorisée à lire. Vérifiez qu’un Build Worker dédié est en ligne, que le projet dispose de la bonne définition de build et que les Build Secrets limités à la source nécessaires sont disponibles. Les Build Secrets sont destinés à la frontière de build isolée ; la configuration d’exécution est publique et ne doit pas contenir ces secrets.

Examinez le package.json du dépôt lorsqu’il sert à la détection du build, choisissez le gestionnaire de paquets et la commande de build appropriés, et assurez-vous que la sortie est un artefact de site statique. Un déploiement Git ne rend pas un environnement d’exécution applicatif côté serveur disponible via Pages.

Le connecteur ne doit disposer que d’un accès en lecture aux dépôts sélectionnés. Le Build Worker a besoin d’une capacité suffisante pour l’installation des dépendances et le build statique, mais ne doit pas partager d’espace de travail modifiable avec des charges de travail de production. Les Build Secrets limités à la source ne sont disponibles qu’à l’intérieur de la frontière de build isolée et ne doivent jamais être copiés dans les fichiers statiques générés ni dans la configuration d’exécution publique.

Définir le succès avant d’activer l’automatisation

Consignez la branche attendue, la racine de l’application, le gestionnaire de paquets, la version de Node.js, le script de build, le répertoire de l’artefact, le tag de publication et le responsable. Définissez ensuite la vérification de recette du site produit : document d’entrée attendu, comportement de la navigation directe, chargement des ressources, métadonnées, Routes par langue, plan du site ou index de recherche le cas échéant, et absence de secrets dans l’artefact.

Activez les builds automatiques lorsque chaque mise à jour pertinente de la source doit produire un candidat. N’activez le déploiement automatique que lorsque chaque candidat réussi peut déplacer sans danger le tag configuré. Pour les sites de documentation et marketing, un build automatique avec promotion explicite en production permet d’examiner d’abord l’aperçu immuable. Les builds utilisent l’identifiant du connecteur et ne dépendent pas des scopes Git actuels de qui que ce soit ; integrations:<provider>:use sur le dépôt n’est nécessaire que pour connecter la source ou modifier son connecteur, son dépôt ou sa branche. Voir Qui peut lancer des builds et consulter les résultats ?.

Construire un déploiement

1. Sélectionnez le dépôt, la branche et la révision prévue pour le projet Pages.
2. Configurez la détection du build, le gestionnaire de paquets, la commande de build et les Build Secrets limités à la source.
3. Lancez le build et suivez l’opération sur le Build Worker isolé qui lui est attribué.
4. Examinez le journal de build masqué, le résultat de la politique, la révision source et la sortie immuable.
5. Créez ou sélectionnez le Deployment obtenu, puis testez-le avant de déplacer un tag de production.

Le build est volontairement séparé de la publication. Un build terminé crée un Deployment immuable candidat ; il ne modifie ni tag personnalisé ni Route. Le build automatique et le déploiement automatique doivent être traités comme des contrôles indépendants, le déploiement automatique n’étant activé qu’une fois le chemin de santé, de promotion et de retour arrière compris.

Promouvoir et vérifier

Déplacez le tag prévu vers le Deployment approuvé. Les Routes ciblent ce tag ; ce déplacement constitue donc l’événement de promotion. Vérifiez le comportement DNS et TLS du domaine public, le document et les ressources statiques renvoyés, window.runtime.config visible côté client et l’état des opérations du projet. Utilisez un aperçu immuable, lorsqu’il est configuré, pour examiner un artefact précis sans déplacer un tag public.

Gardez disponible un Deployment précédent réputé sain pendant la fenêtre de retour arrière. La configuration d’exécution doit rester compatible tant que le même tag peut sélectionner l’une ou l’autre version : la modifier peut changer le comportement du site sans créer de nouveau Deployment ni modifier les empreintes des artefacts.

Build en échec, annulation et retour arrière

Un build en échec ou annulé ne doit pas modifier la version publique active. Examinez l’attribution du worker et les journaux pour distinguer les échecs d’autorisation de la source, de dépendances, de commande de build, de Build Secret, de politique ou de sortie de l’artefact. Corrigez la cause et réessayez ; chaque nouvelle tentative crée une nouvelle opération au lieu de modifier le résultat historique.

Pendant une mise à jour d’Opfield, les builds déclenchés par webhook ou par interrogation périodique sont différés et démarrent une fois la mise à jour terminée.

Si une version promue provoque un incident, ramenez le tag de la Route sur le Deployment vérifié précédent. Vérifiez ensuite la réponse de la route, les ressources, la configuration d’exécution et l’état de l’application nginx. Ne modifiez pas et ne remplacez pas sur place le Deployment en échec : son enregistrement immuable est important pour le diagnostic et comme preuve du retour arrière.

Détails pour l’opérateur : classification des échecs de build

Classez l’échec avant de réessayer :

Domaine de l’échec	Éléments typiques	Action suivante sûre
Autorisation de la source	Le dépôt ou la révision ne peut pas être lu	Réparez les permissions du connecteur ; n’élargissez pas par défaut l’accès à toute l’organisation
Installation des dépendances	Erreur de fichier de verrouillage, de registre ou de gestionnaire de paquets	Reproduisez avec le même gestionnaire de paquets et le même fichier de verrouillage ; ne vérifiez que le secret de registre nécessaire
Commande de build	Script terminé avec un code non nul ou sortie du framework manquante	Corrigez le build du dépôt et conservez la tâche en échec pour comparaison
Contrat d’artefact	Répertoire de sortie manquant, vide ou non statique	Corrigez le répertoire de l’artefact ou la sortie du build ; ne publiez pas un répertoire partiel
Politique ou admission	Build refusé avant publication	Résolvez le constat de politique signalé ou obtenez une exception explicitement approuvée
Publication	Le Deployment existe mais le tag ou la Route n’a pas bougé	Examinez les paramètres de déploiement automatique et l’opération Pages ; ne reconstruisez pas un artefact valide

L’annulation arrête l’opération de build active, mais ne supprime pas les Deployments précédents et ne déplace pas un tag de production existant. La relance d’un build conserve l’empreinte SHA exacte du commit du build d’origine, ce qui rend la relance reproductible même si la branche configurée a avancé. Lancez un nouveau build de source lorsque la nouvelle tête de branche est l’entrée souhaitée.

Versions manuelles et nettoyage

Une version Pages manuelle suit le même modèle de promotion : créez un nouveau Deployment immuable à partir de l’artefact statique préparé, vérifiez-le, et ne déplacez un tag que lorsqu’il est prêt. L’historique Git est utile pour la provenance, mais n’est pas nécessaire pour qu’un artefact manuel participe au même cycle de vie des tags et des Routes.

Lorsque vous déconnectez une source Git, décidez quels Deployments existants restent nécessaires pour le retour arrière. Retirer la source arrête les futurs builds pilotés par la source ; cela ne dépublie pas automatiquement un tag existant et ne supprime pas un artefact déployé. Examinez les références des tags et la conservation avant de supprimer tout Deployment.

Pour les dépôts sensibles, examinez les journaux de build avant de les partager. Opfield masque les Build Secrets gérés, mais les scripts de build peuvent toujours afficher le contenu du dépôt ou dériver des valeurs sensibles. Traitez la définition du build comme du code de production et gardez les secrets hors des commandes, des noms de fichiers, des manifestes générés et des bundles clients.