Integrar o GitLab Runner com servidores remotos via SSH é uma prática comum para automatizar o deploy de aplicações. Este guia detalha o processo de configuração de chaves criptográficas e a preparação do ambiente dentro de containers para permitir conexões seguras e sem intervenção manual.

1. Geração do Par de Chaves Criptográficas

O primeiro passo consiste em gerar uma chave RSA ou Ed25519 que será utilizada especificamente para o processo de CI/CD. No terminal, execute o seguinte comando:

ssh-keygen -t rsa -b 4096 -C "gitlab-deploy-key"

Ao ser solicitado o local de salvamento, você pode definir um diretório específico. Note que serão gerados dois arquivos: a chave privada (ex: id_rsa) e a chave pública (ex: id_rsa.pub).

2. Configuração do Servidor de Destino

Para que o Runner consiga se conectar ao servidor remoto, a chave pública deve ser autorizada no usuário que executará as tarefas de deploy. Supondo a criação de um usuário dedicado chamado deploy_user:

# Criar o diretório de configuração SSH caso não exista
mkdir -p /home/deploy_user/.ssh
chmod 700 /home/deploy_user/.ssh

# Criar e editar o arquivo de chaves autorizadas
vi /home/deploy_user/.ssh/authorized_keys

Cole o conteúdo completo do arquivo id_rsa.pub (gerado no passo anterior) dentro do arquivo authorized_keys. Garanta que as permissões estejam corretas para evitar erros de autenticação:

chmod 600 /home/deploy_user/.ssh/authorized_keys
chown -R deploy_user:deploy_user /home/deploy_user/.ssh

3. Teste de Conexão Manual

Antes de automatizar, valide a conexão a partir de uma máquina que possua a chave privada:

ssh -i ./id_rsa deploy_user@192.168.1.100

Se o acesso for concedido sem solicitação de senha, a configuração no servidor está correta.

4. Preparação do Ambiente no GitLab Runner

Quando o GitLab Runner utiliza o executor Docker, ele inicia containers temporários que não possuem as chaves SSH nativamente. Para resolver isso, utilizaremos um volume montado para injetar as credenciais.

Arquivos de Configuração Necessários

Crie um diretório no host onde o GitLab Runner está instalado (ex: /srv/gitlab-runner/ssh-configs/) e adicione os seguintes arquivos:

1. id_rsa: A chave privada gerada no passo 1.
2. config: Um arquivo de configuração SSH para desabilitar a verificação rigorosa de hosts (evitando prompts interativos de "yes/no").

Conteúdo sugerido para o arquivo config:

Host *
    StrictHostKeyChecking no
    UserKnownHostsFile /dev/null

5. Ajuste no arquivo config.toml do Runner

Edite o arquivo de configuração do GitLab Runner (geralmente em /etc/gitlab-runner/config.toml) para montar o volume que contém as chaves dentro dos containers de build.

[[runners]]
  name = "docker-deploy-runner"
  url = "https://gitlab.example.com/"
  executor = "docker"
  [runners.docker]
    image = "alpine:latest"
    privileged = false
    # Mapeamento do diretório do host para o container
    volumes = ["/srv/gitlab-runner/ssh-configs:/etc/ssh-deploy:ro", "/cache"]

6. Utilização no Script de CI/CD

Dentro do seu arquivo .gitlab-ci.yml, você pode agora utilizar as chaves montadas. É necesário garantir que as permissões da chave privada estejam corrretas antes do uso, pois volumes montados podem herdar permissões inadequadas para o SSH.

deploy_job:
  stage: deploy
  script:
    - mkdir -p ~/.ssh
    - cp /etc/ssh-deploy/id_rsa ~/.ssh/id_rsa
    - cp /etc/ssh-deploy/config ~/.ssh/config
    - chmod 600 ~/.ssh/id_rsa
    - ssh deploy_user@192.168.1.100 "bash /opt/scripts/update_app.sh"

Esta abordagem centraliza a gestão das chaves no host do Runner, evitando que segredos sensíveis sejam expostos diretamente no código-fonte ou em variáveis de ambiente menos seguras quando o volume de dados é alto.