Atualizar o GitHub Enterprise Server

Preparar para a atualização

1. Determine uma estratégia de atualização e escolha uma versão para atualizar. Para obter mais informações, consulte "Requisitos de atualização".

2. Crie um backup da instância primária usando o GitHub Enterprise Server Backup Utilities. Para obter mais informações, consulte o Arquivo README.md do GitHub Enterprise Server Backup Utilities.

3. 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: o período 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, consulte "Habilitar e programar o modo de manutenção".

Sobre os requisitos mínimos para GitHub Enterprise Server 3.0 ou posterior

Antes de atualizar para GitHub Enterprise Server 3.0 ou posterior, revise os recursos de hardware que você forneceu para sua instância. GitHub Enterprise Server 3.0 introduz novas funcionalidades, como GitHub Actions e GitHub Package Registry, e exige mais recursos do que as versões 2.22 e anteriores. Para obter mais informações, consulte as observações sobre a versão GitHub Enterprise Server 3.0.

Os requisitos aumentados para GitHub Enterprise Server 3.0 e posterior estão em negrito na tabela a seguir.

Para obter mais informações sobre requisitos de hardware para GitHub Actions, consulte "Introdução a GitHub Actions para GitHub Enterprise Server".

Para obter mais informações sobre o ajuste de recursos para uma instância existente, consulte "aumentar a capacidade de armazenamento" e "aumentar recursos de CPU ou memória".

Obter um instantâneo

Instantâneo é um ponto de verificação de uma máquina virtual (VM) em um momento específico. É altamente recomendável obter um instantâneo antes de atualizar sua máquina virtual para que você possa recuperar a VM em caso de falha. 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:

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

• Instantâneos em disco de dados salvam somente os dados do usuário.

  Notas:

  • 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.

Atualizar com hotpatch

Você pode atualizar GitHub Enterprise Server para a versão mais recente do patch usando um hotpatch, que não requer uma janela de manutenção e geralmente não requer reinicialização. Você pode usar hotpatching para atualizar para uma versão de patch mais recente, mas não uma versão de recursos. Por exemplo, você pode atualizar 2.10.1 para 2.10.5 porque eles estão na mesma série de recursos, mas não de 2.10.9 para 2.11.0 porque eles estão em uma série de recursos diferentes. Ao usar o Console de gerenciamento, é possível instalar um hotpatch na mesma hora ou programar a instalação para depois. Você pode usar o shell administrativo para instalar um hotpatch com o utilitário ghe-upgrade. Para obter mais informações, consulte "Requisitos de atualização".

Atualizar um appliance com hotpatch

Instalar um hotpatch usando o Console de gerenciamento

1. Habilite atualizações automáticas. Para obter mais informações, consulte "Habilitar atualizações automáticas".
2. A partir de uma conta administrativa em GitHub Enterprise Server, clique em no canto superior direito de qualquer página.
3. Na barra lateral esquerda, clique em Console de gerenciamento.
4. No topo do Console de gerenciamento, clique em Updates.
5. Quando um novo hotpatch for baixado, use o menu suspenso Install package (Instalar pacote):
   • Para instalar na mesma hora, selecione Now (Agora):
   • Para instalar depois, selecione outra data.
6. Clique em instalar.

Instalar hotpatch usando o shell administrativo

1. SSH em sua instância do GitHub Enterprise Server. Para obter mais informações, consulte "Acessar o shell administrativo (SSH)".

   $ ssh -p 122 admin@HOSTNAME

2. Navegue até GitHub Enterprise Server Releases page. Ao lado da versão para a qual você está atualizando, clique em Download e depois clique na aba Upgrading. Copie a URL do hotpackage de atualização (arquivo .hpkg).
3. Baixe o pacote de atualização para 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 de arquivo do pacote:

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

5. Se for necessário reinicializar para aplicar as atualizações no kernel, MySQL, Elasticsearch ou em outros programas, você receberá uma notificação do script de atualização do hotpatch.

Atualizar um appliance com instâncias de réplica usando hotpatch

Appliances configurados para alta disponibilidade e replicação geográfica usam instâncias de réplica, além de instâncias principais. Para atualizar esses appliance, você terá que atualizar a instância primária e todas as instâncias de réplica, uma por vez.

Atualizar a instância primária

1. Atualize a instância primária seguindo as instruções em "Instalar hotpatch usando o shell administrativo".

Atualizar uma instância de réplica

1. Atualize a réplica primária seguindo as instruções em "Instalar hotpatch usando o shell administrativo". Se você estiver usando várias réplicas de replicação geográfica, você deverá repetir esse procedimento para atualizar cada réplica por vez.

2. Conecte-se à instância de réplica sobre o SSH como o usuário "admin" na porta 122:

   $ ssh -p 122 admin@replica-host

3. Verifique a atualização executando:

   $ ghe-version

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, use um pacote ao atualizar da versão 2.11.10 para a 2.12.4, já que elas estão em séries diferentes. Para obter mais informações, consulte "Requisitos de atualização".

Atualizar um appliance com pacote de atualização

1. SSH em sua instância do GitHub Enterprise Server. Para obter mais informações, consulte "Acessar o shell administrativo (SSH)".

   $ ssh -p 122 admin@HOSTNAME

2. Navegue até GitHub Enterprise Server Releases page. Ao lado da versão para a qual você está atualizando, clique em Download e depois clique na aba Upgrading. Selecione a plataforma adequada e copie a URL do pacote de atualização (arquivo .pkg).

3. Baixe o pacote de atualização para 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, consulte "Habilitar e programar o modo de manutenção".

   Observação: ao atualizar o appliance primário em uma configuração de alta disponibilidade, o appliance já deverá estar no modo de manutenção se você seguir as instruções em "Atualizar a instância primária".

5. Execute o comando ghe-upgrade usando o nome de arquivo do 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, e a instância é reiniciada automaticamente em modo de manutenção:

   *** aplicando atualização...
   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. Em atualizações de appliance único, desabilite o modo de manutenção para os usuários poderem trabalhar com a sua instância do GitHub Enterprise Server.

   Observação: ao atualizar appliances em configurações de alta disponibilidade, mantenha o modo de manutenção até atualizar todas as réplicas e a replicação estar atual. Para obter mais informações, consulte "Atualizar instância de réplica".

Atualizar um appliance com instâncias de réplica usando um pacote de atualização

Appliances configurados para alta disponibilidade e replicação geográfica usam instâncias de réplica, além de instâncias principais. Para atualizar esses appliance, você terá que atualizar a instância primária e todas as instâncias de réplica, uma por vez.

Atualizar a instância primária

1. Na instância primária, habilite o modo de manutenção e aguarde a conclusão de todos os processos ativos. Para obter mais informações, consulte "Habilitar o modo de manutenção".
2. Conecte-se à instância de réplica sobre o SSH como o usuário "admin" na porta 122:

   $ ssh -p 122 admin@replica-host

3. Na instância de réplica (ou em todas as instâncias de réplica), se você estiver executando várias réplicas como parte da replicação geográfica, execute ghe-repl-stop para parar a replicação.
4. Atualize a instância primária seguindo as instruções em "Atualizar um appliance com pacote de atualização".

Atualizar uma instância de réplica

1. Atualize a réplica primária seguindo as instruções em "Atualizar um aplicativo com pacote de atualização". Se você estiver usando várias réplicas de replicação geográfica, você deverá repetir esse procedimento para atualizar cada réplica por vez.

2. Conecte-se à instância de réplica sobre o SSH como o usuário "admin" na porta 122:

   $ ssh -p 122 admin@replica-host

3. Verifique a atualização executando:

   $ ghe-version

4. Na instância da réplica, para iniciar a replicação, execute ghe-repl-start.

5. Na instância da réplica, para garantir que os serviços de replicação estejam funcionando corretamente, 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. Se o comando retornar Replicação não executada, pode ser que a replicação ainda esteja começando. Aguarde cerca de um minuto para executar ghe-repl-status novamente.

   Observação: enquanto a ressincronização estiver em andamento, o código ghe-repl-status pode retornar mensagens esperadas indicando que a replicação está atrasada. Por exemplo: CRÍTICO: a replicação git está atrás do primário em mais de 1007 repositórios e/ou gists

   Se ghe-repl-status não retornar OK, siga estas etapas para iniciar a replicação manualmente.

   1. Na instância de réplica, execute ghe-repl-setup <primary-instance-ip> mais uma vez.
   2. Na instância da réplica, para iniciar a replicação, execute ghe-repl-start.
   3. Na instância da réplica, para garantir que os serviços de replicação estejam funcionando corretamente, 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.

6. Ao concluir a atualização da última réplica e quando a ressincronização terminar, desabilite o modo de manutenção para que os usuários possam trabalhar na 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 o switch --allow-patch-rollback. Ao reverter uma atualização, você deve usar um arquivo de atualização com a extensão .pkg. Arquivos de pacotes de hotpatch com a extensão .hpkg não são suportados.

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.

Para obter mais informações, consulte "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, consulte "Obter um instantâneo".