Como Instalar GitLab no Ubuntu: Guia Completo Passo a Passo

GitLab é uma das plataformas DevOps de código aberto mais poderosas disponíveis atualmente, oferecendo um conjunto abrangente de ferramentas, incluindo controle de versão baseado em Git, pipelines de integração contínua/entrega contínua (CI/CD), rastreamento de problemas e recursos de colaboração em equipe — tudo em um só lugar. Quer você esteja gerenciando uma pequena equipe de desenvolvimento ou executando projetos de software em escala empresarial, auto-hospedar GitLab no Ubuntu oferece controle total sobre seus dados, fluxos de trabalho e infraestrutura.

Este guia o orienta em cada etapa da instalação e configuração do GitLab Community Edition (CE) em um servidor Ubuntu, desde a preparação inicial do sistema até a ativação de HTTPS e gerenciamento de serviços.

Pré-requisitos

Antes de começar, certifique-se de ter o seguinte em vigor:

• Um servidor executando Ubuntu 20.04 ou 22.04 LTS (instalação limpa recomendada)
• Um mínimo de 4 GB RAM e 2 núcleos de CPU (GitLab recomenda pelo menos 4 núcleos para uso em produção)
• Acesso root ou sudo ao servidor
• Um nome de domínio registrado apontando para o endereço IP do seu servidor (opcional, mas fortemente recomendado para HTTPS)
• Portas 80 e 443 abertas em seu firewall

> Dica: Para o melhor desempenho do GitLab, considere implantar em um plano de VPS Hosting com RAM e recursos de CPU suficientes. Os planos VPS da AlexHost são otimizados para cargas de trabalho Linux e vêm com acesso root completo, tornando-os um ambiente ideal para plataformas DevOps auto-hospedadas como GitLab.

Etapa 1: Atualizar Pacotes do Sistema

Antes de instalar qualquer software, é crítico garantir que o índice de pacotes do seu sistema e os pacotes instalados estejam totalmente atualizados. Isso evita conflitos de dependência e garante que você esteja trabalhando com os patches de segurança mais recentes.

sudo apt update && sudo apt upgrade -y

Aguarde a conclusão do processo de atualização antes de prosseguir para a próxima etapa.

Etapa 2: Instalar Dependências Necessárias

GitLab requer vários pacotes de suporte para funcionar corretamente, incluindo ferramentas para comunicação segura, gerenciamento de fuso horário e scripts. Instale-os com o seguinte comando:

sudo apt install -y curl openssh-server ca-certificates tzdata perl

Aqui está o que cada pacote faz:

Etapa 3: Adicionar o Repositório Oficial do GitLab

GitLab mantém um repositório de pacotes oficial que torna a instalação e futuras atualizações simples. Use o seguinte comando para baixar e executar o script de configuração do repositório:

curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash

Este script automaticamente:

• Detecta sua versão do Ubuntu
• Adiciona o repositório de pacotes do GitLab às suas fontes APT
• Importa a chave de assinatura GPG do repositório para verificação de pacotes

Após a conclusão do script, seu sistema está pronto para instalar GitLab diretamente da fonte oficial.

Etapa 4: Instalar GitLab Community Edition

Agora instale GitLab CE usando o gerenciador de pacotes apt. Você deve definir a variável de ambiente EXTERNAL_URL para a URL ou endereço IP através do qual os usuários acessarão sua instância GitLab.

Se você tiver um nome de domínio:

sudo EXTERNAL_URL="https://gitlab.yourdomain.com" apt install gitlab-ce

Se você estiver usando um endereço IP (por exemplo, para um servidor local ou privado):

sudo EXTERNAL_URL="http://YOUR_SERVER_IP" apt install gitlab-ce

Substitua gitlab.yourdomain.com ou YOUR_SERVER_IP pelo seu domínio ou endereço IP real.

> Nota: O processo de instalação pode levar vários minutos, pois baixa e configura todos os componentes do GitLab, incluindo PostgreSQL, Redis, NGINX e Sidekiq.

Durante a instalação, GitLab irá:

• Instalar todos os serviços agrupados (banco de dados, cache, servidor web, etc.)
• Configurar-se com base no EXTERNAL_URL que você forneceu
• Gerar arquivos de configuração iniciais em /etc/gitlab/

Etapa 5: Executar a Reconfiguração do GitLab

Após a instalação, execute o comando de reconfiguração para finalizar a configuração, inicializar o banco de dados e iniciar todos os serviços do GitLab:

sudo gitlab-ctl reconfigure

Este comando lê a configuração de /etc/gitlab/gitlab.rb e aplica todas as configurações. Ele também gera certificados SSL (se Let’s Encrypt estiver configurado), configura o esquema do banco de dados e inicia todos os serviços de fundo necessários.

Você deve ver uma longa saída terminando com uma mensagem semelhante a:

gitlab Reconfigured!

Etapa 6: Acessar GitLab no Seu Navegador Web

Após a conclusão da reconfiguração, abra seu navegador web e navegue até a URL que você especificou durante a instalação:

https://gitlab.yourdomain.com

ou

http://YOUR_SERVER_IP

Login pela Primeira Vez

Na sua primeira visita, GitLab solicitará que você defina uma senha de administrador. Após defini-la, faça login usando as seguintes credenciais:

• Nome de usuário: root
• Senha: A senha que você acabou de criar

> Dica de Segurança: Altere as credenciais padrão da conta root imediatamente após seu primeiro login. Crie uma conta de administrador pessoal e restrinja a conta root apenas para uso de emergência.

Etapa 7: Configurar Notificações de Email do GitLab (Opcional)

Enviar notificações por email é essencial para uma instância GitLab em produção — permite recursos como verificação de conta, atualizações de solicitação de mesclagem, alertas de CI/CD e redefinições de senha. Configure as configurações SMTP no arquivo de configuração principal do GitLab:

sudo nano /etc/gitlab/gitlab.rb

Adicione ou modifique o seguinte bloco de configuração SMTP:

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "smtp.yourmailprovider.com"
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "your_email@yourdomain.com"
gitlab_rails['smtp_password'] = "your_email_password"
gitlab_rails['smtp_domain'] = "yourdomain.com"
gitlab_rails['smtp_authentication'] = "login"
gitlab_rails['smtp_enable_starttls_auto'] = true

Salve o arquivo e aplique as alterações:

sudo gitlab-ctl reconfigure

> Procurando por uma infraestrutura de email confiável? AlexHost oferece serviços profissionais de Email Hosting que se integram perfeitamente com aplicações auto-hospedadas como GitLab, fornecendo retransmissão SMTP estável com alta capacidade de entrega.

Etapa 8: Ativar HTTPS com Let’s Encrypt (Recomendado)

Executar GitLab sobre HTTPS é fortemente recomendado para qualquer ambiente de produção ou equipe. GitLab tem suporte integrado para Let’s Encrypt, uma autoridade de certificado SSL gratuita e automatizada.

> Importante: Let’s Encrypt requer que seu nome de domínio seja acessível publicamente e que a porta 80 esteja aberta no seu servidor. Não funcionará com endereços IP brutos.

Abra o arquivo de configuração do GitLab:

sudo nano /etc/gitlab/gitlab.rb

Adicione a seguinte configuração:

letsencrypt['enable'] = true
letsencrypt['contact_emails'] = ['your_admin_email@yourdomain.com']
letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = 12
letsencrypt['auto_renew_minute'] = 30
letsencrypt['auto_renew_day_of_month'] = "*/7"

Salve o arquivo e reconfigure GitLab:

sudo gitlab-ctl reconfigure

GitLab obterá e instalará automaticamente seu certificado SSL, e a configuração auto_renew garante que ele seja renovado antes do vencimento sem qualquer intervenção manual.

> Alternativa: Se você preferir gerenciar certificados SSL independentemente ou precisar de certificados curinga/multi-domínio, AlexHost oferece uma variedade de Certificados SSL que podem ser configurados manualmente nas configurações NGINX do GitLab.

Etapa 9: Gerenciando Serviços do GitLab

GitLab agrupa sua própria ferramenta de gerenciamento de serviços chamada gitlab-ctl. Use os seguintes comandos para controlar os serviços do GitLab:

Iniciar GitLab

sudo gitlab-ctl start

Parar GitLab

sudo gitlab-ctl stop

Reiniciar GitLab

sudo gitlab-ctl restart

Verificar Status do Serviço

sudo gitlab-ctl status

Visualizar Logs em Tempo Real

sudo gitlab-ctl tail

Visualizar Logs de um Serviço Específico (por exemplo, NGINX)

sudo gitlab-ctl tail nginx

Esses comandos são inestimáveis para solução de problemas e manutenção rotineira. O comando status exibirá o estado de todos os sub-serviços do GitLab, incluindo PostgreSQL, Redis, Sidekiq, Puma (servidor web) e NGINX.

Etapa 10: Configuração Inicial do GitLab para Sua Organização

Com GitLab instalado e em execução, é hora de configurá-lo para as necessidades da sua equipe. Aqui estão as principais áreas a configurar através da interface web do GitLab:

Gerenciamento de Usuários

Navegue até Área de Administração → Usuários para criar contas de usuário para os membros da sua equipe. Você pode configurar métodos de autenticação, incluindo LDAP, OAuth e SAML para logon único empresarial.

Grupos e Projetos

• Grupos permitem que você organize projetos relacionados e gerencie permissões em escala
• Projetos são repositórios individuais com seus próprios rastreadores de problemas, wikis e pipelines de CI/CD

Pipelines de CI/CD

O CI/CD integrado do GitLab é um de seus recursos mais poderosos. Crie um arquivo .gitlab-ci.yml na raiz do seu repositório para definir pipelines automatizados de construção, teste e implantação.

Configurações do Repositório

Configure regras de proteção de branch, aprovações de solicitação de mesclagem e fluxos de trabalho de revisão de código na seção Configurações → Repositório de cada projeto.

Configuração de Backup

Configure backups automatizados configurando o seguinte em /etc/gitlab/gitlab.rb:

gitlab_rails['backup_path'] = "/var/opt/gitlab/backups"
gitlab_rails['backup_keep_time'] = 604800  # Keep backups for 7 days

Execute um backup manual a qualquer momento com:

sudo gitlab-backup create

Configuração de Firewall

Se você tiver UFW (Uncomplicated Firewall) ativado no seu servidor Ubuntu, certifique-se de permitir tráfego HTTP e HTTPS:

sudo ufw allow http
sudo ufw allow https
sudo ufw allow OpenSSH
sudo ufw enable
sudo ufw status

Solução de Problemas Comuns