Atualizar o GitHub Enterprise Server

Sobre as atualizações para o GitHub Enterprise Server

O GitHub Enterprise Server está sempre em aprimoramento, com novas funcionalidades e correções de erros introduzidas por meio de recursos e versões de patches. Você é responsável por atualizações de sua instância. Para obter mais informações, confira "Sobre atualizações para novas versões".

Para atualizar uma instância, planeje e comunique a atualização, escolha o pacote apropriado, faça backup dos dados e, em seguida, execute a atualização.

Pré-requisitos

Para atualizar o sua instância do GitHub Enterprise Server com sucesso, o disco de dados da instância deve ter pelo menos 15% de espaço livre. A GitHub recomenda que haja mais armazenamento livre no disco. Em alguns casos raros, para clientes com grandes volumes de dados, esse limite pode ser diferente.

Ao atualizar, verificações prévias avaliam se os requisitos mínimos de recursos de hardware do sistema, como memória, núcleos de CPU e armazenamento no disco raiz e no disco de usuário, estão disponíveis para a instância. Se as verificações prévias determinarem que não há recursos suficientes ou qualquer outra falha, você será notificado e a atualização será cancelada.

Preparar para a atualização

Para se preparar para a atualização, planeje seu caminho, atualize os executores do GitHub Actions (opcional) e agende uma janela de manutenção.

1. Determine uma estratégia de atualização e escolha uma versão para atualizar. Para saber mais, confira "Requisitos de atualização" e veja o Assistente de atualização a fim de localizar o caminho de atualização da versão atual.

2. Crie um backup do nó primário da instância com os GitHub Enterprise Server Backup Utilities. Para saber mais, confira o LEIAME na documentação do projeto do GitHub Enterprise Server Backup Utilities.

   Observação: sua versão do GitHub Enterprise Server Backup Utilities precisa ser a mesma versão ou no máximo duas versões posteriores de sua instância do GitHub Enterprise Server. Para obter mais informações, confira "Como configurar backups em sua instância".

3. Se a sua instância do GitHub Enterprise Server usar executores efêmeros auto-hospedados para o GitHub Actions e você tiver desabilitado as atualizações automáticas, atualize os executores para a versão do aplicativo executor que a instância atualizada executará. Para encontrar a versão mínima necessária para seu lançamento, consulte "Versões do GitHub Enterprise Server".

4. Se você estiver atualizando com um pacote de atualização, programe um período de manutenção para os usuários finais do GitHub Enterprise Server. Se estiver usando um hotpatch, não será necessário recorrer ao modo de manutenção.

   Observação: a janela de manutenção depende do tipo de atualização a ser feita. Atualizações com hotpatch normalmente não exigem período de manutenção. É preciso reinicializar a instância em alguns casos, mas o processo pode ser feito em outro momento. Seguindo o esquema de versões do MAJOR.FEATURE.PATCH, as versões de patch que usam pacote de atualização costumam gerar menos de cinco minutos de tempo de inatividade. Versões de recursos que incluem migrações de dados levam mais tempo, dependendo do desempenho do armazenamento e da quantidade de dados migrados. Para obter mais informações, confira "Habilitar e programar o modo de manutenção".

Obter um instantâneo

Um instantâneo armazena o estado de uma VM (máquina virtual) em um determinado momento. Uma grande recomendação da GitHub é realizar um instantâneo antes de atualizar a máquina virtual para que seja possível recuperá-la em caso de falha. A GitHub só recomenda realizar um instantâneo da VM da instância quando ela está desligada ou quando a instância está no modo de manutenção e todos os trabalhos em segundo plano foram concluídos.

Se você estiver atualizando para uma nova versão do recurso, obtenha um instantâneo da VM. Se você estiver atualizando para uma versão de patch, vincule o disco de dados existente.

Há dois tipos de instantâneo:

• Os instantâneos de VM salvam todo o estado da VM, incluindo os dados do usuário e da configuração. Esse método de instantâneo é demorado e requer muito espaço livre em disco.

• Os instantâneos de disco de dados salvam apenas os dados do usuário.

  Observações:

  • Algumas plataformas não permitem usar instantâneos apenas do disco de dados. Nesse caso, você terá que obter um instantâneo de toda a VM.
  • Se o hipervisor não der suporte a instantâneos completos de VM, obtenha um instantâneo do disco raiz e do disco de dados em rápida sucessão.

Plataforma	Método Snapshot	Documentação
Amazon AWS	Disco	Criar instantâneos do Amazon EBS na documentação da AWS
Azure	VM	Criar um snaphot de um disco rígido virtual em uma VM do Azure no Microsoft Learn
Hyper-V	VM	Habilitar ou desabilitar pontos de verificação no Hyper-V no Microsoft Learn
Google Compute Engine	Disco	Criar e gerenciar instantâneos de disco na documentação do Google Cloud
VMware	VM	Criar instantâneos de uma máquina virtual no VMware Docs

Escolher um pacote de atualização

É possível atualizar uma instância do GitHub Enterprise Server para uma nova versão de patch ou de recurso. No caso da atualização para uma versão de patch, é possível usar um patch dinâmico ou um pacote de atualização. No caso da atualização para uma versão de recurso, use um pacote de upgrade.

Uma instância do GitHub Enterprise Server é composta por um ou mais nós. O processo de atualização a ser seguido depende de quantos nós a instância tem. Para obter mais informações, confira "Sobre o GitHub Enterprise Server".

• Atualizar com hotpatch
  • Atualizar uma instância autônoma usando um patch dinâmico
  • Atualizar uma instância com vários nós usando um patch dinâmico
• Atualizar com pacote de atualização
  • Atualizar uma instância autônoma usando um pacote de atualização
  • Atualizar uma instância com vários nós usando um pacote de atualização

Atualizar com hotpatch

Você pode atualizar o GitHub Enterprise Server para a versão mais recente do patch usando um hotpatch.

Você pode usar hotpatching para atualizar para uma versão de patch mais recente, mas não uma versão de recursos. Por exemplo, é possível atualizar da 2.10.1 para a 2.10.5 porque elas estão na mesma série de recursos, mas não da 2.10.9 para a 2.11.0 porque elas estão em séries de recursos diferentes.

Os hotpatches geralmente não exigem reinicialização. Se um hotpatch exigir uma reinicialização, as notas de versão do GitHub Enterprise Server indicarão o requisito.

Os hotpatches exigem uma execução de configuração, o que pode causar um breve período de erros ou falta de resposta para alguns ou todos os serviços em sua instância do GitHub Enterprise Server. Você não precisa habilitar o modo de manutenção durante a instalação de um hotpatch, mas isso garantirá que os usuários vejam uma página de manutenção em vez de erros ou tempos limite. Para obter mais informações, confira "Habilitar e programar o modo de manutenção".

Ao usar o Console de Gerenciamento, você pode instalar um hotpatch imediatamente ou programá-lo para instalação posterior. Você pode usar o shell administrativo para instalar um patch dinâmico com o utilitário ghe-upgrade. Para obter mais informações, confira "Requisitos de atualização".

• Atualizar uma instância autônoma usando um patch dinâmico
• Atualizar uma instância com vários nós usando um patch dinâmico

Atualizar uma instância autônoma usando um patch dinâmico

Para atualizar uma instância com um nó usando um patch dinâmico, se o destino for uma versão de patch, será possível realizar a atualização por meio do Console de Gerenciamento. Para atualizar para uma versão de recurso, use o shell administrativo.

• Instalar um hotpatch usando o Console de Gerenciamento
• Instalar hotpatch usando o shell administrativo

Instalar um hotpatch usando o Console de Gerenciamento

Você pode usar o Console de Gerenciamento para atualizar com um hotpatch, habilitando as atualizações automáticas. Em seguida, será apresentada a última versão de GitHub Enterprise Server disponível para a qual você pode atualizar.

Se a meta de atualização for a versão do recurso ao invés do patch, você não poderá usar Console de Gerenciamento para instalar o hotpatch. Você deve instalar o hotpatch usando o shell administrativo. Para obter mais informações, confira "Como instalar um patch dinâmico usando o shell administrativo".

1. Habilitar as atualizações automáticas. Para obter mais informações, confira "Verificações de atualizações automáticas".

2. Em uma conta administrativa no GitHub Enterprise Server, no canto superior direito de qualquer página, clique em .

3. Se você ainda não estiver na página "Administração do site", no canto superior esquerdo, clique em Administração do site.

4. Na barra lateral " Administrador do site", clique em Console de Gerenciamento .

5. Na barra de navegação superior, clique em Atualizações.

   

6. Quando um novo patch dinâmico for baixado, selecione o menu suspenso Instalar pacote.

   • Para instalar imediatamente, clique em Agora.
   • Para instalar depois, selecione outra data.

7. Clique em Instalar.

Instalar hotpatch usando o shell administrativo

1. Conecte-se via SSH ao sua instância do GitHub Enterprise Server. Se sua instância for composta por vários nós, por exemplo, se a alta disponibilidade ou a replicação geográfica estiver configurada, efetue SSH no nó primário. Se você usar um cluster, poderá efetuar SSH em qualquer nó. Substitua HOSTNAME pelo nome do host da instância ou pelo nome do host ou endereço IP de um nó. Para obter mais informações, confira "Acesar o shell administrativo (SSH)".

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Navegue até a página Versões do GitHub Enterprise Server. Ao lado da versão para a qual você está atualizando, clique em Baixar e clique na guia Upgrade. Copie a URL do pacote dinâmico de atualização (arquivo .hpkg).

3. Baixe o pacote de atualização no sua instância do GitHub Enterprise Server usando curl:

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

4. Execute o comando ghe-upgrade usando o nome do arquivo de pacote:

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

5. Se pelo menos um serviço ou componente do sistema exigir uma reinicialização, o script de atualização de patch dinâmico notificará você. Por exemplo, as atualizações no kernel, no MySQL ou no Elasticsearch podem exigir uma reinicialização.

Atualizar uma instância com vários nós usando um patch dinâmico

Para instalar um patch dinâmico, não é necessário entrar no modo de manutenção ou interromper a replicação.

• Atualizar o nó primário usando um patch dinâmico
• Atualizar nós adicionais usando um patch dinâmico

Atualizar o nó primário usando um patch dinâmico

Para obter instruções a fim de atualizar o nó primário, confira "Como instalar um patch dinâmico usando o shell administrativo".

Atualizar nós adicionais usando um patch dinâmico

Para atualizar uma instância com diversos nós, como uma configuração de alta disponibilidade ou replicação geográfica, repita o procedimento a seguir em cada nó de réplica, um por vez.

1. Para atualizar o nó, siga as instruções descritas em "Como instalar um patch dinâmico usando o shell administrativo".

2. Conecte-se ao nó de réplica via SSH como o usuário admin na porta 122:

   ssh -p 122 admin@REPLICA_HOST
   

3. Verifique a atualização executando:

   ghe-version
   

4. Repita as etapas acima para cada nó adicional.

Atualizar com pacote de atualização

Mesmo que seja possível usar um hotpatch para fazer a atualização do patch em uma série, você deve usar um pacote de atualização a fim de atualizar para uma versão mais recente. Por exemplo, para atualizar da 2.11.10 para a 2.12.4, é preciso usar um pacote de atualização porque essas versões estão em séries de recursos diferentes. Para obter mais informações, confira "Requisitos de atualização".

• Atualizar uma instância autônoma usando um pacote de atualização
• Atualizar uma instância com vários nós usando um pacote de atualização

Atualizar uma instância autônoma usando um pacote de atualização

1. Conecte-se via SSH ao sua instância do GitHub Enterprise Server. Se sua instância for composta por vários nós, por exemplo, se a alta disponibilidade ou a replicação geográfica estiver configurada, efetue SSH no nó primário. Se você usar um cluster, poderá efetuar SSH em qualquer nó. Substitua HOSTNAME pelo nome do host da instância ou pelo nome do host ou endereço IP de um nó. Para obter mais informações, confira "Acesar o shell administrativo (SSH)".

   Shell

   ssh -p 122 admin@HOSTNAME
   

2. Navegue até a página Versões do GitHub Enterprise Server. Ao lado da versão para a qual você está atualizando, clique em Baixar e clique na guia Upgrade. Selecione a plataforma adequada e copie a URL do pacote de atualização (arquivo .pkg).

3. Baixe o pacote de atualização no sua instância do GitHub Enterprise Server usando curl:

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

4. Habilite o modo de manutenção e aguarde a conclusão de todos os processos ativos na instância do GitHub Enterprise Server. Para obter mais informações, confira "Habilitar e programar o modo de manutenção".

   Observação: ao atualizar o nó primário em uma configuração de alta disponibilidade, a instância já deve estar no modo de manutenção ao seguir as instruções em "Atualização do nó primário com um pacote de atualização".

5. Execute o comando ghe-upgrade usando o nome do arquivo de pacote:

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

6. Confirme que você gostaria de continuar a atualização e de reiniciar após a verificação da assinatura do pacote. O novo sistema de arquivos raiz grava na partição secundária. A instância, por sua vez, é reiniciada automaticamente em modo de manutenção:

   *** 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. Opcionalmente, durante uma atualização para uma versão de recurso, é possível monitorar o status das migrações de banco de dados usando o utilitário ghe-migrations. Para obter mais informações, confira "Utilitários de linha de comando".

8. Depois que a instância for reiniciada, a atualização continuará em segundo plano. Não é possível remover a definição do modo de manutenção até que o processo seja concluído.

Para verificar o status dos trabalhos em segundo plano, use o utilitário ghe-check-background-upgrade-jobs. Se você estiver com atualizações consecutivas em execução, deverá se certificar de que os trabalhos em segundo plano estejam concluídos antes de prosseguir com a atualização seguinte para uma versão de recurso. Para usar esse utilitário com o GitHub Enterprise Server 3.9, a instância deve executar a versão 3.9.7 ou versões posteriores. Para obter mais informações sobre o utilitário, confira “Utilitários de linha de comando”.

Para monitorar o progresso da execução da configuração, realize a leitura da saída em /data/user/common/ghe-config.log. Por exemplo, você pode acompanhar o log executando o seguinte comando:

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

1. Opcionalmente, após a atualização, é possível validá-la configurando uma lista de exceções de IP para permitir o acesso a uma lista especificada de endereços IP. Para obter mais informações, confira "Habilitar e programar o modo de manutenção".

2. Para atualizações de nó único, desabilite o modo de manutenção a fim de que os usuários possam usar o sua instância do GitHub Enterprise Server.

   Observação: após a atualização de uma instância em uma configuração de alta disponibilidade, mantenha-se no modo de manutenção até concluir a atualização de todos os nós de réplica e a replicação estar atual. Para saber mais, confira "Como atualizar nós adicionais com um pacote de atualização".

Atualizar uma instância com vários nós usando um pacote de atualização

Para atualizar uma instância com vários nós usando um pacote de atualização, faça a atualização do nó primário e, em seguida, de todos os nós adicionais.

• Atualizar o nó primário com um pacote de atualização
• Atualizar nós adicionais com um pacote de atualização

Atualizar o nó primário com um pacote de atualização

1. No nó primário, habilite o modo de manutenção e aguarde a conclusão de todos os processos ativos. Para obter mais informações, confira "Habilitar e programar o modo de manutenção".

2. Conecte-se ao nó de réplica via SSH como o usuário admin na porta 122:

   ssh -p 122 admin@REPLICA_HOST
   

3. Para interromper a replicação em todos os nós, execute ghe-repl-stop em cada um deles.

4. Para atualizar o nó primário, siga as instruções em "Atualizar um uma instância autônoma usando um pacote de atualização".

Atualizar nós adicionais com um pacote de atualização

Para atualizar uma instância com diversos nós, como uma configuração de alta disponibilidade ou replicação geográfica, repita o procedimento a seguir em cada nó de réplica, um por vez.

1. Atualize o nó seguindo as instruções em "Atualizar um uma instância autônoma usando um pacote de atualização".

2. Conecte-se ao nó de réplica via SSH como o usuário admin na porta 122:

   ssh -p 122 admin@REPLICA_HOST
   

3. Verifique a atualização executando:

   ghe-version
   

4. No nó de réplica, execute ghe-repl-start para iniciar a replicação.

5. No nó de réplica, para garantir a execução correta dos serviços de replicação, execute ghe-repl-status. Este comando retornará OK para todos os serviços quando uma replicação bem sucedida estiver em andamento e a réplica for atualizada. Quando o comando retorna Replication is not running, isso significa que a replicação ainda pode estar sendo iniciada. Aguarde cerca de um minuto antes de executar ghe-repl-status novamente.

   Observações:

   • Embora a ressincronização esteja em andamento, ghe-repl-status pode indicar que a replicação está atrasada. Nesses casos, será possível ver a mensagem a seguir.

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

   • Se o GitHub Actions estiver ativado em sua instância do GitHub Enterprise Server, você poderá ver uma mensagem como a seguinte. Essa mensagem é esperada quando a replicação é pausada devido à definição do modo de manutenção no dispositivo primário. Quando a definição do modo de manutenção for removida, essa mensagem será resolvida.

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

   Se ghe-repl-status não retornou OK e a explicação não estiver listada na nota acima, entre em contato com o Suporte do GitHub Enterprise. Para obter mais informações, confira "Entrando em contato com o suporte do GitHub".

6. Repita as etapas acima para cada nó adicional.

7. Após a atualização do último nó de réplica e da conclusão da ressincronização, desabilite o modo de manutenção para que os usuários possam usar o sua instância do GitHub Enterprise Server.

Restaurar após uma atualização com falha

Em caso de falha ou interrupção da atualização, volte a sua instância ao estado anterior. Esse processo dependerá do tipo de atualização.

Voltar a uma versão de patch

Para reverter uma versão de patch, use o comando ghe-upgrade com a opção --allow-patch-rollback. Antes de realizar a reversão, a replicação precisa ser interrompida temporariamente por meio da execução de ghe-repl-stop em todos os nós de réplica. Ao reverter uma atualização, você precisa usar um arquivo de pacote de atualização com a extensão .pkg. Não há suporte para arquivos de pacote de patch dinâmico com a extensão .hpkg.

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

É necessário reinicializar após a execução do comando. Reverter não afeta a partição de dados, pois as migrações não são executadas nas versões de patch.

Depois que a reversão for concluída, reinicie a replicação executando ghe-repl-start em todos os nós.

Para obter mais informações, confira "Utilitários de linha de comando".

Voltar a uma versão de recurso

Para voltar a partir de uma versão de recurso, faça a restauração partindo de um instantâneo da VM para garantir o estado consistente das partições raiz e de dados. Para obter mais informações, confira "Como criar um instantâneo".

Leitura adicional

• "Sobre atualizações para novas versões"