Mise à niveau de GitHub Enterprise Server

À propos des mises à niveau vers GitHub Enterprise Server

GitHub Enterprise Server s’améliore constamment grâce aux mises en production de fonctionnalités et de patchs. Celles-ci incluent en effet de nouvelles fonctionnalités et des correctifs de bogues. Vous êtes responsable des mises à niveau vers votre instance. Pour plus d’informations, consultez « À propos des mises à niveau vers de nouvelles mises en production ».

Pour mettre à niveau une instance, vous devez planifier et communiquer la mise à niveau, choisir le package approprié, sauvegarder vos données et effectuer la mise à niveau.

Prérequis

Pour réussir la mise à niveau de votre instance GitHub Enterprise Server, le disque de données de l’instance doit avoir un espace libre d’au moins 15 %. GitHub recommande de vous assurer qu’il y a davantage de stockage libre sur le disque. Dans certains cas rares, pour les clients avec de grands volumes de données, ce seuil peut différer.

Lors de la mise à niveau, les vérifications de préversion évaluent si la configuration minimale requise pour les ressources matérielles système, telles que la mémoire, les cœurs de processeur et le stockage sur disque racine et utilisateur, sont disponibles pour votre instance. Si les vérifications de préversion déterminent qu’il y a des ressources insuffisantes ou échouent, vous êtes averti et la mise à niveau est abandonnée.

Préparation à une mise à niveau

Pour préparer une mise à niveau, prévoyez le chemin de mise à niveau, mettez éventuellement à niveau les exécuteurs GitHub Actions et planifiez une fenêtre de maintenance.

1. Établissez une stratégie de mise à niveau et choisissez la version cible de la mise à niveau. Pour plus d’informations, consultez « Conditions à remplir pour la mise à niveau » et Assistant Mise à niveau pour connaître le chemin de mise à niveau à partir de votre version actuelle.

2. Créez une nouvelle sauvegarde du nœud principal de votre instance avec GitHub Enterprise Server Backup Utilities. Pour plus d’informations, consultez le README dans la documentation du projet GitHub Enterprise Server Backup Utilities.

   Remarque : Votre version de GitHub Enterprise Server Backup Utilities doit être identique à, ou au plus deux versions ultérieures à, votre instance GitHub Enterprise Server. Pour plus d’informations, consultez « Configuration des sauvegardes sur votre instance ».

3. Si votre instance GitHub Enterprise Server utilise des exécuteurs auto-hébergés éphémères pour GitHub Actions et que vous avez désactivé les mises à jour automatiques, mettez à niveau vos exécuteurs vers la version de l’application d’exécuteur que votre instance mise à niveau exécutera. Pour trouver la version minimale requise pour votre version, consultez « Versions de GitHub Enterprise Server ».

4. Si vous effectuez une mise à niveau à partir d’un package de mise à niveau, planifiez une fenêtre de maintenance pour les utilisateurs finaux de GitHub Enterprise Server. Si vous utilisez un patch à chaud, le mode maintenance n’est pas obligatoire.

   Remarque : La fenêtre de maintenance dépend du type de mise à niveau que vous effectuez. Les mises à niveau utilisant un patch à chaud ne nécessitent généralement pas de fenêtre de maintenance. Parfois, un redémarrage est exigé, ce que vous pouvez faire ultérieurement. Suivant le schéma de contrôle de version de MAJOR.FEATURE.PATCH, les versions correctives utilisant un package de mise à niveau demandent généralement un temps d’arrêt de moins de cinq minutes. Les mises en production de fonctionnalités qui incluent des migrations de données prennent plus de temps, selon le niveau de performance du stockage et la quantité de données à migrer. Pour plus d’informations, consultez « Activation et planification du mode de maintenance ».

Capture d’un instantané

Un instantané stocke l’état d’une machine virtuelle à un moment donné. GitHub recommande vivement de prendre un instantané avant de mettre à niveau votre machine virtuelle. En cas d’échec de la mise à niveau, vous pourrez ainsi revenir à l’instantané de votre machine virtuelle. GitHub recommande de prendre un instantané de machine virtuelle seulement si la machine virtuelle de l’instance est hors tension ou si l’instance est en mode maintenance et que tous les travaux en arrière-plan sont terminés.

Si vous effectuez une mise à niveau vers une nouvelle mise en production de fonctionnalité, vous devez capturer un instantané de machine virtuelle. Si vous effectuez une mise à niveau vers une version corrective, vous pouvez joindre le disque de données existant.

Il existe deux types d’instantanés :

• Les instantanés de machine virtuelle enregistrent l’état complet de la machine virtuelle, avec les données utilisateur et les données de configuration. Cette méthode de capture d’instantané demande une grande quantité d’espace disque et s’avère fastidieuse.

• Les instantanés de disque de données enregistrent uniquement vos données utilisateur.

  Remarques :

  • Certaines plateformes ne vous permettent pas de capturer seulement un instantané de votre disque de données. Pour ces plateformes, vous devez capturer un instantané de l’ensemble de la machine virtuelle.
  • Si votre hyperviseur ne prend pas en charge les instantanés complets de machines virtuelles, vous devez capturer un instantané du disque racine et du disque de données de manière successive et rapide.

Plateforme	Snapshot (méthode)	Documentation
Amazon AWS	Disque	Créer des instantanés Amazon EBS dans la documentation AWS
Azure	Machine virtuelle	Créer un instantané d’un disque dur virtuel sur une machine virtuelle Azure dans Microsoft Learn
Hyper-V	Machine virtuelle	Activer ou désactiver des points de contrôle dans Hyper-V de Microsoft Learn
Google Compute Engine	Disque	Créer et gérer des instantanés de disque dans la documentation Google Cloud
VMware	Machine virtuelle	Prise d’instantanés d’une machine virtuelle dans VMware Docs

Choix d’un package de mise à niveau

Vous pouvez mettre à niveau une instance GitHub Enterprise Server vers une nouvelle version corrective ou vers une nouvelle version de fonctionnalité. Pour effectuer une mise à niveau vers une version corrective, vous pouvez utiliser un patch à chaud ou un package de mise à niveau. Pour effectuer une mise à niveau vers une version de fonctionnalité, vous devez utiliser un package de mise à niveau.

Une instance GitHub Enterprise Server comprend un ou plusieurs nœuds. Le processus de mise à niveau que vous devez suivre dépend du nombre de nœuds de votre instance. Pour plus d’informations, consultez « À propos du serveur GitHub Enterprise ».

• Mise à niveau avec un patch à chaud
  • Mise à niveau d’une instance autonome en utilisant un patch à chaud
  • Mise à niveau d’une instance avec plusieurs nœuds en utilisant un patch à chaud
• Mise à niveau avec un package de mise à niveau
  • Mise à niveau d’une instance autonome en utilisant un package de mise à niveau
  • Mise à niveau d’une instance avec plusieurs nœuds en utilisant un package de mise à niveau

Mise à niveau avec un patch à chaud

Vous pouvez mettre à niveau GitHub Enterprise Server vers la dernière version corrective en utilisant un patch à chaud.

Vous pouvez utiliser la mise à niveau à chaud pour effectuer une mise à niveau vers une version de correctif plus récente, mais pas une mise en production de fonctionnalité. Par exemple, vous pouvez effectuer une mise à niveau de 2.10.1 vers 2.10.5, parce qu’ils sont dans la même série de fonctionnalités, mais pas de 2.10.9 vers 2.11.0 parce qu’ils sont dans des séries de fonctionnalités différentes.

Les patchs à chaud ne nécessitent généralement pas de redémarrage. Si un patch à chaud nécessite un redémarrage, les notes de publication de GitHub Enterprise Server indiquent la configuration requise.

Les patchs à chaud nécessitent une exécution de configuration, qui peut provoquer une brève période d’erreurs ou d’absence de réponse pour tout ou partie des services sur votre instance GitHub Enterprise Server. Vous n’êtes pas obligé d’activer le mode maintenance pendant l’installation d’un patch à chaud, mais cela garantit que les utilisateurs voient une page de maintenance au lieu de messages d’erreur ou d’expiration de délai. Pour plus d’informations, consultez « Activation et planification du mode de maintenance ».

La Management Console vous permet d’installer un patch à chaud immédiatement ou de planifier une installation ultérieure. Vous pouvez utiliser l’interpréteur de commandes d’administration pour installer un patch à chaud avec l’utilitaire ghe-upgrade. Pour plus d’informations, consultez « Conditions à remplir pour la mise à niveau ».

• Mise à niveau d’une instance autonome en utilisant un patch à chaud
• Mise à niveau d’une instance avec plusieurs nœuds en utilisant un patch à chaud

Mise à niveau d’une instance autonome en utilisant un patch à chaud

Si vous mettez à niveau une instance avec un nœud à l’aide d’un patch à chaud et que votre cible est une version corrective, vous pouvez effectuer la mise à niveau en utilisant la Management Console. Pour effectuer une mise à niveau vers une mise en production de fonctionnalité, vous devez utiliser l’interpréteur de commandes d’administration.

• Installation d’un patch à chaud à l’aide de la Management Console
• Installation d’un patch à chaud à l’aide de l’interpréteur de commandes d’administration

Installation d’un patch à chaud à l’aide de la Management Console

Vous pouvez utiliser la Management Console pour effectuer une mise à niveau avec un patch à chaud en activant les mises à jour automatiques. La dernière version disponible de GitHub Enterprise Server vers laquelle effectuer une mise à niveau vous sera alors présentée.

Si la cible de mise à niveau qui vous êtes présentée est une mise en production de fonctionnalité et non une version corrective, vous ne pourrez pas utiliser vous servir de la Management Console pour installer un patch à chaud. Au lieu de cela, vous devrez installer le patch à chaud à l’aide de l’interpréteur de commandes d’administration. Pour plus d’informations, consultez « Installation d’un patch à chaud à l’aide de l’interpréteur de commandes d’administration ».

1. Activer les mises à jour automatiques. Pour plus d’informations, consultez « Activation de la recherche de mises à jour automatiques ».

2. À partir d’un compte d’administration sur GitHub Enterprise Server, cliquez sur en haut à droite de n’importe quelle page.

3. Si vous ne figurez pas déjà sur la page « Administrateur du site », dans le coin supérieur gauche, cliquez sur Administrateur du site.

4. Dans la barre latérale «  Administrateur de site », cliquez sur Management Console .

5. Dans la barre de navigation supérieure, cliquez sur Mises à jour.

   

6. Après avoir téléchargé un nouveau patch à chaud, sélectionnez le menu déroulant Installer le package.

   • Pour l’installer immédiatement, cliquez sur Maintenant.
   • Pour une installation ultérieure, sélectionnez une date ultérieure.

7. Cliquez sur Installer.

Installation d’un patch à chaud à l’aide de l’interpréteur de commandes d’administration

1. Connexion SSH à votre instance GitHub Enterprise Server. Si votre instance comprend plusieurs nœuds, par exemple si la haute disponibilité ou la géoréplication sont configurées, connectez-vous via SSH au nœud principal. Si vous utilisez un cluster, vous pouvez vous connecter via SSH à n’importe quel nœud. Remplacez HOSTNAME par le nom d’hôte de votre instance, le nom d’hôte ou l’adresse IP d’un nœud. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Accédez à la page des versions de GitHub Enterprise Server. En regard de la version vers laquelle vous effectuez une mise à niveau, cliquez sur Télécharger, puis sur l’onglet Mise à niveau. Copiez l’URL du package à chaud de mise à niveau (fichier .hpkg).

3. Téléchargez le package de mise à niveau sur votre instance GitHub Enterprise Server en utilisant curl :

   admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL
   

4. Exécutez la commande ghe-upgrade en utilisant le nom de fichier du package :

   admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.hpkg
   *** verifying upgrade package signature...
   

5. Si au moins un service ou un composant système nécessite de redémarrer, le script de mise à niveau du patch à chaud vous en avertit. Par exemple, les mises à jour de noyau, de MySQL ou d’Elasticsearch peuvent nécessiter un redémarrage.

Mise à niveau d’une instance avec plusieurs nœuds en utilisant un patch à chaud

Si vous installez un patch à chaud, vous n’avez pas besoin de passer en mode maintenance ou d’arrêter la réplication.

• Mise à niveau du nœud principal à l’aide d’un patch à chaud
• Mise à niveau des nœuds supplémentaires à l’aide d’un patch à chaud

Mise à niveau du nœud principal à l’aide d’un patch à chaud

Pour obtenir des instructions permettant de mettre à niveau le nœud principal, consultez « Installation d’un patch à chaud à l’aide de l’interpréteur de commandes d’administration ».

Mise à niveau des nœuds supplémentaires à l’aide d’un patch à chaud

Pour mettre à niveau une instance qui comprend plusieurs nœuds, tels qu’une configuration de haute disponibilité ou de géoréplication, vous devez répéter la procédure suivante sur chaque nœud de réplica, un par un.

1. Pour mettre à niveau le nœud, suivez les instructions dans « Installation d’un patch à chaud à l’aide de l’interpréteur de commandes d’administration ».

2. Connectez-vous au nœud de réplica via SSH en tant qu’utilisateur admin sur le port 122 :

   ssh -p 122 admin@REPLICA_HOST
   

3. Vérifiez la mise à niveau en exécutant :

   ghe-version
   

4. Répétez les étapes ci-dessus pour chaque nœud supplémentaire.

Mise à niveau avec un package de mise à niveau

Bien que vous puissiez utiliser un patch à chaud pour effectuer une mise à niveau vers la dernière mise en production de fonctionnalité d’une série de fonctionnalités, vous devez utiliser un package de mise à niveau pour effectuer une mise à niveau vers une mise en production de fonctionnalité plus récente. Par exemple, pour effectuer une mise à niveau de 2.11.10 vers 2.12.4, vous devez utiliser un package de mise à niveau, car il ne s’agit pas de la même séries de fonctionnalités. Pour plus d’informations, consultez « Conditions à remplir pour la mise à niveau ».

• Mise à niveau d’une instance autonome en utilisant un package de mise à niveau
• Mise à niveau d’une instance avec plusieurs nœuds en utilisant un package de mise à niveau

Mise à niveau d’une instance autonome en utilisant un package de mise à niveau

1. Connexion SSH à votre instance GitHub Enterprise Server. Si votre instance comprend plusieurs nœuds, par exemple si la haute disponibilité ou la géoréplication sont configurées, connectez-vous via SSH au nœud principal. Si vous utilisez un cluster, vous pouvez vous connecter via SSH à n’importe quel nœud. Remplacez HOSTNAME par le nom d’hôte de votre instance, le nom d’hôte ou l’adresse IP d’un nœud. Pour plus d’informations, consultez « Accès à l’interpréteur de commandes d’administration (SSH) ».

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Accédez à la page des versions de GitHub Enterprise Server. En regard de la version vers laquelle vous effectuez une mise à niveau, cliquez sur Télécharger, puis sur l’onglet Mise à niveau. Sélectionnez la plateforme appropriée et copiez l’URL du package de mise à niveau (fichier .pkg).

3. Téléchargez le package de mise à niveau sur votre instance GitHub Enterprise Server en utilisant curl :

   admin@HOSTNAME:~$ curl -L -O UPGRADE-PKG-URL
   

4. Activez le mode maintenance et attendez que tous les processus actifs se terminent sur l’instance GitHub Enterprise Server. Pour plus d’informations, consultez « Activation et planification du mode de maintenance ».

   Remarque : Si vous mettez à niveau le nœud principal dans une configuration à haute disponibilité, l’instance doit déjà être en mode maintenance si vous suivez les instructions dans « Mise à niveau du nœud principal avec un package de mise à niveau ».

5. Exécutez la commande ghe-upgrade en utilisant le nom de fichier du package :

   admin@HOSTNAME:~$ ghe-upgrade GITHUB-UPGRADE.pkg
   *** verifying upgrade package signature...
   

6. Confirmez votre volonté de poursuivre la mise à niveau et de redémarrer une fois la signature du package vérifiée. Le nouveau système de fichiers racine écrit dans la partition secondaire et l’instance redémarre automatiquement en mode maintenance :

   *** applying update...
   This package will upgrade your installation to version VERSION-NUMBER
   Current root partition: /dev/xvda1 [VERSION-NUMBER]
   Target root partition:  /dev/xvda2
   Proceed with installation? [y/N]
   

7. Si vous le souhaitez, lors d’une mise à niveau vers une mise en production de fonctionnalité, vous pouvez surveiller l’état des migrations de bases de données à l’aide de l’utilitaire ghe-migrations. Pour plus d’informations, consultez « Utilitaires de ligne de commande ».

8. Une fois l’instance redémarrée, la mise à niveau continue en arrière-plan. Vous ne pouvez pas annuler le mode de maintenance tant que le processus n’est pas terminé.

Pour vérifier l’état des tâches en arrière-plan, utilisez l’utilitaire ghe-check-background-upgrade-jobs. Si vous exécutez des mises à niveau consécutives, vous devez vous assurer que les tâches en arrière-plan sont terminées avant de passer à la mise à niveau suivante vers une version de fonctionnalité. Pour utiliser cet utilitaire avecGitHub Enterprise Server 3.9, votre instance doit exécuter la version 3.9.7 ou une version ultérieure. Pour plus d’informations sur l’utilitaire, consultez « Utilitaires de ligne de commande ».

Pour surveiller la progression de l’exécution de la configuration, lisez la sortie dans /data/user/common/ghe-config.log. Par exemple, vous pouvez suivre le journal en exécutant la commande suivante :

tail -f /data/user/common/ghe-config.log

1. Si vous le souhaitez, après la mise à niveau, validez celle-ci en configurant une liste d’exceptions d’IP pour autoriser l’accès à une liste d’adresses IP spécifiée. Pour plus d’informations, consultez « Activation et planification du mode de maintenance ».

2. Pour les mises à niveau d’un seul nœud, désactivez le mode maintenance pour permettre aux utilisateurs d’utiliser votre instance GitHub Enterprise Server.

   Remarque : Après avoir mis à niveau une instance dans une configuration à haute disponibilité, vous devez rester en mode maintenance tant que vous n’avez pas mis à niveau tous les nœuds de réplica et que la réplication est en cours. Pour plus d’informations, consultez « Mise à niveau de nœuds supplémentaires avec un package de mise à niveau ».

Mise à niveau d’une instance avec plusieurs nœuds en utilisant un package de mise à niveau

Pour mettre à niveau une instance qui comprend plusieurs nœuds à l’aide d’un package de mise à niveau, vous devez mettre à niveau le nœud principal, puis mettre à niveau tous les nœuds supplémentaires.

• Mise à niveau du nœud principal avec un package de mise à niveau
• Mise à niveau des nœuds supplémentaires avec un package de mise à niveau

Mise à niveau du nœud principal avec un package de mise à niveau

1. Sur le nœud principal, activez le mode maintenance et attendez que tous les processus actifs se terminent. Pour plus d’informations, consultez « Activation et planification du mode de maintenance ».

2. Connectez-vous au nœud de réplica via SSH en tant qu’utilisateur admin sur le port 122 :

   ssh -p 122 admin@REPLICA_HOST
   

3. Pour arrêter la réplication sur tous les nœuds, exécutez ghe-repl-stop sur chaque nœud.

4. Pour mettre à niveau le nœud principal, suivez les instructions dans « Mise à niveau d’une instance autonome avec un package de mise à niveau ».

Mise à niveau des nœuds supplémentaires avec un package de mise à niveau

Pour mettre à niveau une instance qui comprend plusieurs nœuds, tels qu’une configuration de haute disponibilité ou de géoréplication, vous devez répéter la procédure suivante sur chaque nœud de réplica, un par un.

1. Mise à niveau du nœud principal en suivant les instructions dans « Mise à niveau d’une instance autonome avec un package de mise à niveau ».

2. Connectez-vous au nœud de réplica via SSH en tant qu’utilisateur admin sur le port 122 :

   ssh -p 122 admin@REPLICA_HOST
   

3. Vérifiez la mise à niveau en exécutant :

   ghe-version
   

4. Sur le nœud de réplica, pour démarrer la réplication, exécutez ghe-repl-start.

5. Sur le nœud de réplica, pour vérifier que les services de réplication s’exécutent correctement, exécutez ghe-repl-status. Cette commande retourne OK pour tous les services quand une réplication réussie est en cours et que le réplica a été mis à niveau. Si la commande retourne Replication is not running, la réplication est peut-être toujours en cours de démarrage. Attendez environ une minute avant de réexécuter ghe-repl-status.

   Remarques :

   • Pendant la resynchronisation, ghe-repl-status peut indiquer que la réplication est en retard. Par exemple, vous pouvez voir le message d’erreur suivant.

     CRITICAL: git replication is behind the primary by more than 1007 repositories and/or gists
     

   • Si GitHub Actions est activé sur votre instance GitHub Enterprise Server, un message semblable à ce qui suit peut s’afficher. Ce message est attendu quand la réplication est mise en pause en raison du mode maintenance défini sur l’appliance principale. Quand le mode maintenance est non défini, ce message doit être résolu.

     CRITICAL: mssql replication is down, didn't find Token_Configuration!
     

   Si ghe-repl-status n’a pas renvoyé OK et que l’explication n’est pas répertoriée dans la remarque ci-dessus, contactez Support GitHub Enterprise. Pour plus d’informations, consultez « Contacter le support GitHub ».

6. Répétez les étapes ci-dessus pour chaque nœud supplémentaire.

7. Après avoir mis à niveau le dernier nœud de réplica et que la resynchronisation est terminée, désactivez le mode maintenance pour permettre aux utilisateurs de se servir de votre instance GitHub Enterprise Server.

Restauration à partir d’une mise à niveau avortée

En cas d’échec ou d’interruption d’une mise à niveau, vous devez restaurer votre instance dans son état précédent. La procédure permettant d’effectuer cette opération dépend du type de mise à niveau.

Annulation d’une version corrective

Pour annuler une version corrective, utilisez la commande ghe-upgrade avec le commutateur --allow-patch-rollback. Avant cela, la réplication doit être temporairement arrêtée en exécutant ghe-repl-stop sur tous les nœuds de réplica. Quand vous restaurez une mise à niveau, vous devez utiliser un fichier de package de mise à niveau avec l’extension .pkg. Les fichiers de package de patch à chaud avec l’extension .hpkg ne sont pas pris en charge.

ghe-upgrade --allow-patch-rollback EARLIER-RELEASE-UPGRADE-PACKAGE.pkg

Un redémarrage est nécessaire après l’exécution de cette commande. La restauration n’affecte pas la partition de données, car les migrations ne sont pas exécutées sur les versions de patch.

Une fois l’opération terminée, redémarrez la réplication en exécutant ghe-repl-start sur tous les nœuds.

Pour plus d’informations, consultez « Utilitaires de ligne de commande ».

Annulation d’une mise en production de fonctionnalité

Pour une restauration à partir d’une mise en production de fonctionnalité, restaurez l’instantané d’une machine virtuelle de sorte que les partitions racine et de données se trouvent dans un état cohérent. Pour plus d’informations, consultez « Capture d’un instantané ».

Pour aller plus loin

• "À propos des mises à niveau vers de nouvelles mises en production"