DEV Community: Gabriel Brocco de Oliveira

Como treinei uma IA de suporte com histórico real de atendimento: da conversa bruta ao RAG em produção

Gabriel Brocco de Oliveira — Thu, 21 May 2026 22:49:36 +0000

Esse artigo é a documentação completa do pipeline que construí para extrair conhecimento do histórico real de atendimento de um cliente e transformá-lo em base vetorial para uma IA de suporte em produção.

A linha do tempo: 8.400 conversas brutas viraram 2.200 pares de conhecimento na base final. Sem anotação manual.

Antes de começar: os conceitos

LLM (Large Language Model). O modelo de linguagem em si, como Claude, GPT ou Gemini. Ele é poderoso, mas tem dois problemas: não sabe nada sobre o seu negócio específico, e alucina quando não sabe.

RAG (Retrieval-Augmented Generation). A solução para isso. Antes do LLM responder, você busca o contexto relevante numa base própria e injeta esse contexto no prompt. O modelo deixa de adivinhar e passa a responder a partir de informação real e verificável.

Embedding. A peça que faz a busca funcionar. É um vetor, ou seja, uma lista de números (no nosso caso, 1.536 deles) que representa o "significado" de um texto num espaço matemático. Frases parecidas geram vetores próximos. "Como gerar relatório?" e "Onde vejo o resumo financeiro?" ficam vizinhas no espaço vetorial mesmo sem dividir palavras.

Vetor store. O lugar onde esses vetores ficam armazenados de forma que você consegue perguntar "me dá os 10 mais parecidos com esse aqui" em milissegundos. No nosso caso, Postgres com a extensão pgvector.

Busca semântica vs full-text. Semântica é via embedding: captura sentido. Full-text é match de palavras: captura termos exatos. Cada uma falha em coisas diferentes. A combinação é o que chamam de busca híbrida.

Reranker. Um modelo menor que, depois da busca, reordena os resultados pela relevância real para a query. A busca é boa em achar candidatos. O reranker é bom em decidir a ordem final.

O problema concreto

Plataforma de atendimento ao cliente customizada (Postgres por baixo), meses de histórico de conversas. Duas fontes de conhecimento precisavam alimentar o agente de IA:

*Documentação técnica * — já processada num pipeline de RAG separado, com chunking hierárquico por seção
Histórico de conversas — o desafio desse artigo

O objetivo nunca foi substituir atendentes humanos. Era criar uma primeira camada de resolução automática para as dúvidas recorrentes, que representam cerca de 70% do volume da operação.

Visão geral: o pipeline em 5 estágios

[1] Coleta + filtro de qualidade
        ↓
[2] Classificação estruturada com LLM
        ↓
[3] Geração de embeddings
        ↓
[4] Deduplicação vetorial (greedy clustering)
        ↓
[5] Busca híbrida (full-text search com ts_rank + semântica) + reranker

Cada estágio resolve um problema específico que o anterior não resolve. Vou destrinchar um por um.

Estágio 1 — Coleta e filtro de qualidade

O maior obstáculo de aprender com histórico real é o ruído. Nem toda conversa terminou em resolução. Muitas foram escaladas. Algumas o cliente ficou insatisfeito e nem disse nada. Se você joga tudo na base, ensina o agente a errar do mesmo jeito que o pior atendente do time.

A pergunta é: como filtrar qualidade sem precisar anotar manualmente milhares de conversas?

A resposta pragmática: CSAT (Pontuação de Satisfação do Cliente) como proxy de qualidade. Não é perfeito, já que nem todo bom atendimento recebe avaliação, mas é o sinal mais confiável que já está no banco, de graça.

Além do CSAT, dois filtros adicionais:

Número mínimo de mensagens: conversas muito curtas raramente contêm resolução real. Mínimo de 4 mensagens.
Status resolved: só conversas que a plataforma marcou como resolvidas.

Resultado: de ~8.400 conversas brutas, sobraram ~2.100 qualificadas.

Estágio 2 — Classificação estruturada com LLM

Essa é a parte central do pipeline. Cada conversa qualificada é enviada para um LLM com um prompt de extração estruturada. O modelo recebe o histórico completo de mensagens e devolve JSON com um ou mais qa_pairs.

Por que LLM e não regras? Porque um único ticket pode conter múltiplos problemas diferentes. O cliente começa perguntando sobre relatório, no meio reclama de uma cobrança, no fim pergunta sobre integração. Três tópicos, três pares de conhecimento independentes. Regras de regex não resolvem isso de forma confiável. O LLM identifica os tópicos, separa em pares e classifica cada um individualmente.

Modelo escolhido: Claude Haiku. Rápido e barato o suficiente para processar 2.100 conversas em batch sem virar projeto orçamentário.

A anatomia de um qa_pair

Cada par tem campos com função muito específica:

Campo	Função
`question`	Pergunta essencial reescrita, sem nome de cliente e sem dados do caso específico
`answer`	Solução em prosa, anonimizada. Não é transcrição, é síntese do que resolveu
`resolution_steps`	Array de passos ordenados. O agente usa pra guiar o cliente step-by-step
`domain`	Classificação de alto nível fechada, que define qual setor resolveria
`module`	Área do produto em snake_case livre (ex: `financeiro_app`, `agenda`)
`intent_freetext`	Intent em snake_case (ex: `gerar_relatorio_mensal`)
`resolution_actor`	Quem resolve: `client_self_service` / `agent_in_app` / `agent_backend` / `external_team`
`user_confirmed_resolution`	O cliente confirmou que foi resolvido? Boolean
`confirmation_type`	`explicit` / `implicit_no_return` / `informational_only` / `none`
`confidence`	0.0 a 1.0. Certeza do LLM na extração. Governa o que entra na base
`pii_found`	Boolean. Havia dados pessoais identificáveis na conversa?
`pii_audit`	Detalhamento do PII encontrado e como foi anonimizado

Um exemplo real (anonimizado) do output:

{
  "qa_pairs": [
    {
      "question": "Como gerar relatório de entradas separado por centro de custo?",
      "answer": "Acesse Financeiro > Demonstrativo Financeiro. Selecione o período e o centro de custo desejado. O sistema permite filtros por forma de entrada e separação entre recebimentos e pagamentos. Exportação disponível em PDF.",
      "resolution_steps": [
        "Acessar menu Financeiro",
        "Selecionar Demonstrativo Financeiro",
        "Configurar filtro de período e centro de custo",
        "Aplicar filtros adicionais se necessário",
        "Exportar em PDF"
      ],
      "domain": "tecnico",
      "module": "financeiro_app",
      "intent_freetext": "gerar_relatorio_por_centro_de_custo",
      "topic_tags": ["relatorio", "financeiro", "centro_de_custo"],
      "resolution_actor": "client_self_service",
      "user_confirmed_resolution": true,
      "confirmation_type": "explicit",
      "pii_found": false,
      "pii_audit": [],
      "confidence": 0.94
    }
  ],
  "should_extract": true,
  "quality_concern": null
}

O sistema de domínio em dois níveis

Essa escolha de arquitetura é deliberada e resolve um problema real.

domain é fechado. Só pode assumir valores pré-definidos: tecnico, comercial, assinatura, nfse. Serve pra roteamento e filtro grosso na busca.

module é livre em snake_case. Captura granularidade do produto. O agente de IA usa para filtrar retrieval por área funcional sem depender de uma taxonomia rígida que precisa ser mantida.

O maior erro inicial foi misturar "dúvida sobre o módulo financeiro do app" com "assinatura do serviço". O módulo financeiro do produto é técnico, porque o cliente aprendeu a usar uma feature. Assinatura é sobre o que ele paga pra empresa. Domínios separados, lógicas completamente diferentes, atendentes diferentes.

O papel do confidence na qualidade da base

O confidence não é decoração. Ele governa o que entra na base final.

O LLM atribui confidence baixo quando: a conversa não tinha resolução clara, o cliente saiu sem confirmar, a dúvida era ambígua entre dois domínios, ou havia informação contraditória no histórico.

Threshold estabelecido: 0.75. Pares abaixo disso vão pra fila de revisão manual. Não são descartados automaticamente, mas também não entram direto na base.

Distribuição real após classificação:

confidence ≥ 0.90 → ~43% dos pares
0.75 ≤ confidence < 0.90 → ~38% dos pares
confidence < 0.75 → ~19% (fila de revisão)

~80% do conhecimento aproveitado com qualidade alta, sem anotação humana.

O schema que sustenta o pipeline

Todo esse JSON do LLM precisa virar linhas numa tabela. Toda a engenharia dos próximos estágios (embeddings, deduplicação, busca híbrida) depende de como esse schema é desenhado. Aqui está a tabela de staging que sustenta o pipeline inteiro:

CREATE EXTENSION IF NOT EXISTS vector;

CREATE SCHEMA IF NOT EXISTS rag_sandbox;

CREATE TABLE rag_sandbox.case_knowledge_staging (
    staging_id                BIGSERIAL PRIMARY KEY,
    source_conversation_id    BIGINT NOT NULL,
    extracted_at              TIMESTAMPTZ DEFAULT now(),

    -- Conteúdo extraído do LLM
    question                  TEXT NOT NULL,
    answer                    TEXT NOT NULL,
    resolution_steps          JSONB,

    -- Classificação
    domain                    TEXT NOT NULL CHECK (
                                domain IN ('tecnico','comercial','assinatura','nfse')
                              ),
    module                    TEXT,
    intent_freetext           TEXT,
    topic_tags                TEXT[],
    resolution_actor          TEXT CHECK (
                                resolution_actor IN (
                                  'client_self_service','agent_in_app',
                                  'agent_backend','external_team'
                                )
                              ),

    -- Sinais de qualidade
    user_confirmed_resolution BOOLEAN,
    confirmation_type         TEXT,
    confidence                NUMERIC(3,2) CHECK (confidence BETWEEN 0 AND 1),

    -- Privacidade
    pii_found                 BOOLEAN DEFAULT false,
    pii_audit                 JSONB,

    -- Embeddings (preenchidos no estágio 3)
    embedding_input           TEXT,
    embedding                 vector(1536),
    answer_embedding          vector(1536),

    -- Controle de deduplicação (preenchido no estágio 4)
    dedup_status              TEXT DEFAULT 'pending' CHECK (
                                dedup_status IN ('pending','canonical','duplicate','unique')
                              ),
    duplicate_of              BIGINT REFERENCES rag_sandbox.case_knowledge_staging(staging_id),
    dup_similarity            NUMERIC(5,4),

    -- Coluna full-text (estágio 5)
    fts                       tsvector GENERATED ALWAYS AS (
                                to_tsvector(
                                  'portuguese',
                                  coalesce(question,'') || ' ' || coalesce(answer,'')
                                )
                              ) STORED
);

-- Índice ANN (Approximate Nearest Neighbor) para busca semântica
CREATE INDEX idx_staging_embedding
    ON rag_sandbox.case_knowledge_staging
    USING hnsw (embedding vector_cosine_ops);

-- Índice GIN para full-text search
CREATE INDEX idx_staging_fts
    ON rag_sandbox.case_knowledge_staging USING gin (fts);

-- Índices de filtro
CREATE INDEX idx_staging_domain ON rag_sandbox.case_knowledge_staging (domain);
CREATE INDEX idx_staging_dedup  ON rag_sandbox.case_knowledge_staging (dedup_status);

Três decisões:

O embedding é vector(1536). Essa dimensão vem do modelo text-embedding-3-small da OpenAI. Se trocar de modelo, a dimensão muda. Não dá pra "só rodar o novo modelo" sem reconstruir a coluna e rebuildar o índice.

O índice é HNSW (Hierarchical Navigable Small World). É um algoritmo de busca aproximada que sacrifica precisão mínima por velocidade gigante. Com volume maior, HNSW é o que viabiliza retrieval em milissegundos.

O fts é uma coluna GENERATED ALWAYS AS. O Postgres gera e mantém atualizado o tsvector automaticamente baseado em question + answer, com stemming em português. Combinado com o índice GIN, é o que faz o full-text search do estágio 5 ser instantâneo.

Optamos por ts_rank nativo em vez de BM25 por dois motivos: escala atual de ~2k pares não justifica a complexidade adicional, e o ganho marginal de recall não compensa o overhead operacional.

A tabela de produção (que o agente realmente consulta) é uma view filtrada dessa staging:

CREATE VIEW rag.case_knowledge AS
SELECT *
FROM rag_sandbox.case_knowledge_staging
WHERE dedup_status IN ('canonical', 'unique')
  AND confidence >= 0.75;

Essa separação entre staging e produção é o que permite reprocessar o pipeline (reclassificar, recalibrar threshold, regerar embeddings) sem mexer no que o agente está consultando em tempo real.

Estágio 3 — Geração de embeddings

Aqui tem um detalhe sutil que faz diferença grande.

O texto que vai para o modelo de embedding não é só o question. É a concatenação de question + intent_freetext.

Por quê? Porque perguntas reais são genéricas. "Como faço isso?", "Não está funcionando", "Tá dando erro". O embedding dessas frases sozinhas é fraco, porque vetorialmente elas ficam todas amontoadas numa região do espaço.

O intent_freetext, que o LLM gerou em snake_case durante a classificação, ancora a semântica. "como_faço_isso" combinado com "gerar_relatorio_por_centro_de_custo" gera um vetor muito mais útil do que só "como faço isso?".

O campo answer recebe embedding separado. Isso permite busca bidirecional: pelo lado da pergunta (usuário perguntando algo) ou pelo lado da solução (agente buscando "como resolvo X").

UPDATE rag_sandbox.case_knowledge_staging
SET embedding_input = question || ' ' || replace(intent_freetext, '_', ' ')
WHERE confidence >= 0.75;

-- Após geração via API (batch):
-- modelo: text-embedding-3-small
-- dimensão: 1536

Estágio 4 — Deduplicação vetorial com greedy clustering

2.100 conversas filtradas geraram ~3.400 qa_pairs após classificação. Mas muitos eram semanticamente idênticos: a mesma dúvida resolvida por atendentes diferentes, em palavras diferentes, em meses diferentes.

Jogar tudo na base cria um problema concreto: a busca retorna 5 versões da mesma resposta ocupando o contexto do LLM. Você desperdiça tokens e dilui a qualidade da resposta final.

A solução foi aplicar greedy clustering por distância de cosseno via pgvector. A lógica é simples:

Ordena todos os pares por confidence decrescente
O par com maior confidence vira canonical
Todos os pares com similaridade ≥ threshold viram duplicate, apontando pro canonical
O canonical carrega o melhor conhecimento. Os duplicatas ficam como referência, mas não entram na busca

DO $$
DECLARE
  threshold float := 0.92;  -- 92% de similaridade = duplicata
  pair_record record;
  similar_count integer;
BEGIN
  FOR pair_record IN
    SELECT staging_id, embedding, confidence
    FROM rag_sandbox.case_knowledge_staging
    WHERE embedding IS NOT NULL
      AND dedup_status = 'pending'
    ORDER BY confidence DESC, staging_id
  LOOP
    -- Se já foi marcado como duplicate em iteração anterior, pula
    IF (SELECT dedup_status FROM rag_sandbox.case_knowledge_staging
        WHERE staging_id = pair_record.staging_id) <> 'pending' THEN
      CONTINUE;
    END IF;

    -- Marca similares como duplicate desse canonical
    WITH similares AS (
      UPDATE rag_sandbox.case_knowledge_staging
      SET dedup_status   = 'duplicate',
          duplicate_of   = pair_record.staging_id,
          dup_similarity = 1 - (embedding <=> pair_record.embedding)
      WHERE staging_id <> pair_record.staging_id
        AND dedup_status = 'pending'
        AND embedding IS NOT NULL
        AND (embedding <=> pair_record.embedding) < (1 - threshold)
      RETURNING staging_id
    )
    SELECT count(*) INTO similar_count FROM similares;

    -- Vira canonical (tem similares) ou unique (sem similares)
    UPDATE rag_sandbox.case_knowledge_staging
    SET dedup_status = CASE
      WHEN similar_count > 0 THEN 'canonical'
      ELSE 'unique'
    END
    WHERE staging_id = pair_record.staging_id;
  END LOOP;
END $$;

Vale entender o operador: <=> no pgvector é distância de cosseno. Retorna 0 para vetores idênticos e 2 para opostos. (1 - distância) te dá a similaridade. O threshold de 0.92 foi calibrado empiricamente. Abaixo disso, pares de fato distintos começavam a ser marcados como duplicata. Ajuste conforme a diversidade do seu domínio.

Estágio 5 — Busca híbrida com RRF e reranker

A base final ficou com ~2.200 pares: só os marcados como canonical ou unique, com confidence ≥ 0.75. Mas a base é só metade da equação. Como você busca importa tanto quanto o que tem dentro.

A arquitetura combina dois métodos complementares:

Busca semântica. Boa pra capturar intenção e variação de linguagem. "Como vejo o histórico financeiro?" e "relatório de entradas" têm embeddings próximos, mesmo sem compartilhar palavras.

Full-text. Bom pra termos específicos do produto, como nomes de módulos, botões e telas. "Demonstrativo Financeiro" retorna muito melhor no full-text search com ts_rank do que na busca semântica.

Cada uma falha em coisas diferentes. Sozinhas, deixam buracos. Juntas, se cobrem.

Fundindo os rankings com RRF

O problema de combinar duas buscas é que os scores estão em escalas incomparáveis. Score de ts_rank é uma coisa, score de cosseno é outra. Somar não faz sentido.

A solução elegante é o Reciprocal Rank Fusion (RRF). Em vez de combinar os scores, você combina as posições no ranking. A fórmula:

RRF(d) = Σ  1 / (k + rank_i(d))

Onde k é uma constante (geralmente 60) e rank_i(d) é a posição do documento d no ranking do sistema i. Documento que aparece no top de ambos os rankings ganha pontuação alta. Documento que só aparece num ranking ganha pontuação média. Documento que não aparece em nenhum, zero.

Adaptável a diferentes escalas. Resolve o problema sem hiperparâmetro arbitrário.

O reranker como camada final

Depois do RRF, ainda tem uma jogada. Uma segunda passagem com um modelo reranker sobre os top-20 do RRF. Reordena pela relevância contextual real considerando a query completa.

Por que vale o custo extra? Porque o reranker vê pergunta e candidato juntos, diferente do embedding, que codifica cada um isoladamente. A diferença entre top-5 do RRF e top-5 do reranker era perceptível nas respostas do agente em produção. Vale.

Os números finais

8.400  conversas brutas no banco
2.100  qualificadas (CSAT + status + tamanho mínimo)
3.400  qa_pairs extraídos pelo LLM
2.200  pares na base final (após confidence + dedup)

A redução de 35% via clustering não perdeu cobertura. Perdeu redundância. Os 1.200 pares eliminados eram semanticamente cobertos pelos que ficaram.

Aprendizados

Confidence threshold em 0.75 foi o ponto de equilíbrio. Testamos 0.80 e eliminava conhecimento útil. Testamos 0.70 e ruído real entrava. Esse hiperparâmetro vale o tempo de calibrar, não chute.

Busca híbrida + RRF superou semântica pura, especialmente em termos técnicos específicos do produto. Se a sua base tem jargão, nomes próprios ou rótulos de UI, full-text não é opcional.

resolution_actor virou peça de roteamento, não só metadado. O agente não tenta resolver o que precisa de ação de backend, encaminha direto. Estruturar o conhecimento com esse campo desde a classificação evitou implementar uma camada de orquestração depois.

Embedding de question + intent é melhor que question sozinho. Sutil, mas é a diferença entre busca que funciona e busca que parece funcionar nos testes e falha em produção.

Se você está construindo algo parecido e tem perguntas ou sugestões sobre alguma decisão específica, me chama e vamos conversar.

Como configurar deploy automático da sua API (GO) + Postgres com Docker via GitHub Actions e SSH

Gabriel Brocco de Oliveira — Fri, 30 May 2025 13:24:28 +0000

Nesta publicação, vou te mostrar passo a passo como estruturar seu projeto em Go, configurar o deploy automático com GitHub Actions e subir sua API — utilizando Docker. Ao final, você terá tudo rodando em um servidor remoto via SSH e realizando o deploy de forma automatizada.

1. Arquitetura do projeto

O projeto utilizado como exemplo é um CRUD simples de usuários, bancos e contas bancárias. Porém estruturado utilizando o padrão de arquitetura Ports and Adapters, também conhecido como Arquitetura Hexagonal.

.github/
├── workflows/
│   └── deploy.yml
cmd/
├── config/
│   └── database/
│       └── migrations/
└── main.go
internal/
├── core/
│   ├── domain/
│   │   ├── banco.go
│   │   ├── conta.go
│   │   └── usuario.go
│   ├── dto/
│   │   ├── banco.go
│   │   ├── conta.go
│   │   └── usuario.go
│   └── usecase/
│       ├── banco.go
│       ├── conta.go
│       └── usuario.go
├── infra/
│   ├── controller/
│   │   ├── banco.go
│   │   ├── conta.go
│   │   └── usuario.go
│   ├── repository/
│   │   ├── banco.go
│   │   ├── conta.go
│   │   └── usuario.go
│   └── server/
│       └── server.go
pkg/
└── di/
├── banco.go
├── conta.go
└── usuario.go
.env
.env-example
.gitignore
docker-compose.yml
Dockerfile
go.mod
go.sum
README.md

Dockerfile: este arquivo cria a imagem Docker da nossa API escrita em Go. Ele utiliza uma imagem base (Golang + Alpine), instala as dependências do projeto, compila o código-fonte em um executável e define os comandos para iniciar a aplicação automaticamente quando o contêiner for iniciado.

./Dockerfile

FROM golang:1.24.2-alpine

WORKDIR /app

COPY go.mod go.sum ./

RUN go mod download

COPY . .

WORKDIR /app/cmd

RUN go build -o main .

EXPOSE 8080

CMD ["./main"]

docker-compose.yml: Define dois serviços principais que rodam em seus próprios contêineres Docker: api (nossa aplicação Go) e db (o banco de dados PostgreSQL). Ele configura a comunicação entre eles, garante que o banco de dados esteja totalmente operacional antes de iniciar a API, expõe as portas necessárias e gerencia as credenciais e dados de forma eficiente.

./docker-compose.yml

version: '3.8'

services:
  api:
    build: .
    ports:
      - "8080:8080"
    depends_on:
      db:
        condition: service_healthy
    environment:
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=postgres
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_NAME=banco
    env_file:
      - .env 

  db:
    image: postgres:16-alpine
    ports:
      - "5432:5432"
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=banco
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    env_file:
      - .env 

volumes:
  postgres_data:

2. Configurando o GitHub Secrets

No repositório do GitHub, clique em Settings > Secrets and variables > Actions > New repository secret.

Adicione uma SECRET para cada variável abaixo:

ENV → Variáveis do seu .env que não serão expostas
SSH_HOST → IP ou domínio do seu servidor
SSH_USER → Usuário SSH no servidor (ex: ubuntu)
SSH_PRIVATE_KEY → Conteúdo da chave privada SSH (sem senha)

3. Workflow GitHub Actions para deploy automático

O workflow a seguir realiza os seguintes passos:

Clona o repositório com o código mais recente da branch master.
Cria o arquivo .env dinamicamente, utilizando as variáveis sensíveis armazenadas nos Secrets do GitHub (como senhas e configurações de banco).
Constrói a imagem Docker da aplicação, passando as variáveis do .env como argumentos de build (--build-arg).
Salva a imagem como um arquivo .tar, o que permite transportá-la para o servidor.
Envia a imagem Docker para o servidor remoto via SCP.
Acessa o servidor via SSH, carrega a imagem Docker, remove o container antigo (caso exista), e sobe um novo container com a versão atualizada da API.

deploy.yml: Automatiza a entrega contínua da nossa API Go. Ele serve para garantir que cada nova versão da aplicação seja automaticamente compilada, empacotada em um contêiner Docker e implantada em nosso servidor, minimizando erros manuais e agilizando o ciclo de desenvolvimento.

.github/workflows/deploy.yml

name: Build and Deploy Go API via SSH

on:
  push:
    branches:
      - master

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout do repositório
        uses: actions/checkout@v3

      - name: Criar o arquivo .env com os valores do secret
        run: |
          echo "${{ secrets.ENV }}" > .env

      - name: Construir a imagem Docker
        run: |
          export $(grep -v '^#' .env | xargs) 

          docker build \
            --build-arg DB_PASSWORD=$DB_PASSWORD \
            --build-arg DB_PORT=$DB_PORT \
            --build-arg DB_SSL_MODE=$DB_SSL_MODE \
            -t go-api-banco:latest .

      - name: Salvar imagem como .tar
        run: docker save -o go-api-banco.tar go-api-banco:latest

      - name: Enviar imagem para o servidor via SCP
        uses: appleboy/scp-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: "go-api-banco.tar"
          target: "~/"

      - name: Fazer deploy da imagem via SSH
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            docker load -i ~/go-api-banco.tar
            docker stop go-api-banco || true
            docker rm go-api-banco || true
            docker run -d --name go-api-banco -p 8080:8080 go-api-banco:latest

4. Configurando o servidor remoto

No seu servidor (exemplo Ubuntu):

Instale o Docker
Garanta que seu usuário SSH tenha permissão para rodar Docker (geralmente adicionado ao grupo docker)
Configure sua chave pública SSH no ~/.ssh/authorized_keys do usuário

5. Testando o Deploy

Após fazer o push para o branch master, o GitHub Actions irá iniciar o processo de deploy.

Para verificar se tudo ocorreu como esperado:

Acesse o GitHub → seu repositório → Actions
Veja se o workflow “Build and Deploy Go API via SSH” foi executado com sucesso
Acesse seu servidor no navegador: http://<IP_DO_SERVIDOR>:8080
Sua API Go estará rodando 🎉

6. O que você ganha com essa automação?

Ao automatizar o processo de deploy, você transforma algo que poderia levar vários minutos (ou até horas) em um fluxo confiável de poucos cliques ou um simples git push.

Essa integração entre GitHub Actions, Docker e seu servidor remoto garante:

Segurança: nenhuma senha ou dado sensível é exposto — tudo é gerenciado via GitHub Secrets.
Consistência: o mesmo ambiente é reproduzido em cada deploy, reduzindo erros por diferenças de ambiente.
Velocidade: o deploy leva apenas alguns minutos e requer zero intervenção manual.
Rastreabilidade: cada execução fica registrada nos Actions do GitHub, permitindo rastrear mudanças e reverter se necessário.

Conclusão

Com isso, você tem uma pipeline de deploy automatizada, segura e baseada em tecnologias sólidas como Go, Docker, PostgreSQL e GitHub Actions.

Esse processo elimina deploys manuais, acelera o desenvolvimento e garante que sua API esteja sempre atualizada no servidor.