DEV Community

Cover image for Como integrar Apidog com GitHub e GitLab
Lucas
Lucas

Posted on • Originally published at apidog.com

Como integrar Apidog com GitHub e GitLab

Se suas especificações de API ficam no Apidog, mas a fonte de verdade da equipe está no Git, conecte os dois. A integração Git do Apidog permite vincular um repositório GitHub, GitLab ou Azure DevOps ao projeto, enviar especificações OpenAPI para controle de versão e trazer alterações do repositório de volta para o Apidog. O resultado é um fluxo com histórico, revisão por pull request e backup versionado das especificações.

Experimente o Apidog hoje

Este guia mostra como configurar e operar essa integração na prática: escolher provedor, branch e repositório; decidir entre sincronização bidirecional e backup automático; lidar com permissões, conflitos e falhas comuns. Se você precisa apenas do passo a passo focado em GitHub, veja o guia dedicado sobre como sincronizar sua especificação OpenAPI com o GitHub.

O que a integração Git do Apidog faz

O Apidog se comunica com o Git de duas formas. Antes de configurar, escolha qual delas resolve seu caso de uso.

Visualização mostrando que a integração Apidog Git pode fazer backup unidirecional e sincronização bidirecional. O backup é rotulado como unidirecional, enquanto a sincronização é bidirecional.

Capacidade Direção Gatilho Use quando
Sincronização do Modo Spec-First Bidirecional: push e pull Manual A especificação deve passar por revisão, pull request e histórico Git
Backup automático Git Unidirecional: Apidog → Git Agendado Você quer uma cópia versionada sem mudar o fluxo diário da equipe

Na prática:

  • Use sincronização quando a equipe edita OpenAPI como código.
  • Use backup quando o objetivo é manter snapshots versionados no Git.
  • Use ambos quando quiser edição controlada por Git e uma camada extra de segurança.

Provedores Git suportados

O Apidog suporta GitHub, GitLab e Azure DevOps. A diferença principal está na autenticação.

Provedor Autenticação Observações
GitHub OAuth via login GitHub Funciona com repositórios pessoais e de organização. Organizações podem exigir aprovação de administrador.
GitLab OAuth via login GitLab Suporta gitlab.com e instâncias self-managed acessíveis pelo Apidog.
Azure DevOps Conexão Git genérica via HTTPS + token Use a URL HTTPS do repositório e um PAT com escopo de repositório.

A conexão Git genérica também serve para hosts Git compatíveis com HTTPS e autenticação por token.

Como conectar um repositório Git ao Apidog

O fluxo geral é:

  1. Autorize o provedor Git.
  2. Escolha o repositório.
  3. Escolha o branch.
  4. Configure quem pode sincronizar ou enviar alterações.
  5. Valide o primeiro push ou backup.

GitHub

  1. No Apidog, inicie a conexão com GitHub.
  2. Faça login na tela OAuth do GitHub.
  3. Autorize o acesso ao repositório.
  4. Se o repositório pertence a uma organização, confirme se um administrador aprovou o app.
  5. Selecione o repositório e o branch, normalmente main ou um branch de trabalho.

GitLab

  1. Inicie a conexão com GitLab.
  2. Faça login via OAuth.
  3. Conceda acesso ao repositório.
  4. Para GitLab self-managed, confirme que a instância é acessível pelo Apidog.
  5. Selecione repositório e branch.

Azure DevOps

No Azure DevOps, use a conexão Git genérica:

  1. Copie a URL HTTPS do repositório.
  2. Crie um Personal Access Token, ou PAT.
  3. Dê ao PAT permissão de leitura e escrita em código apenas para o projeto necessário.
  4. Cole a URL HTTPS e o PAT no Apidog.
  5. Escolha o branch de destino.

Exemplo de URL HTTPS típica:

https://dev.azure.com/org/projeto/_git/repositorio
Enter fullscreen mode Exit fullscreen mode

Boas práticas de permissão:

  • Prefira tokens com escopo mínimo.
  • Não use tokens de conta inteira se apenas um repositório precisa ser acessado.
  • Revogue tokens de usuários que saíram da equipe.
  • Para repositórios de organização, confirme a aprovação do app no provedor Git.

Se você ainda está definindo padrões de repositório, veja também o guia sobre controle de versão OpenAPI com Git.

Sincronização bidirecional com o Modo Spec-First

O Modo Spec-First transforma o Apidog em um editor OpenAPI conectado ao Git. Você edita YAML ou JSON, faz commit, envia para o branch conectado e também pode puxar alterações feitas no repositório.

A referência completa está na documentação oficial do Apidog.

Fluxo recomendado

  1. Abra o projeto no Modo Spec-First.
  2. Faça pull antes de editar.
  3. Edite o arquivo OpenAPI em YAML ou JSON.
  4. Valide erros no editor.
  5. Faça commit com uma mensagem clara.
  6. Envie para o branch conectado.
  7. Abra um pull request no Git, se sua equipe usa revisão antes do merge.

Exemplo de alteração em uma especificação OpenAPI:

paths:
  /v1/orders/{orderId}:
    get:
      operationId: getOrder
      summary: Retrieve a single order
      parameters:
        - name: orderId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The requested order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
Enter fullscreen mode Exit fullscreen mode

Depois de salvar, o Apidog trata a alteração como uma edição local. Em seguida, você faz commit e push para o branch conectado.

Uma mensagem de commit útil deve explicar a mudança de contrato da API:

Add GET /v1/orders/{orderId} endpoint
Enter fullscreen mode Exit fullscreen mode

Quando o push termina, o indicador de sincronização mostra que Apidog e Git estão alinhados.

Como trabalhar em equipe

Use o mesmo padrão que você já usa para código:

  1. Crie ou selecione um branch para a alteração.
  2. Faça a mudança na especificação.
  3. Envie o commit.
  4. Abra um pull request.
  5. Revise o diff YAML.
  6. Faça merge após aprovação.

Esse é o núcleo de um fluxo de trabalho de API nativo do Git: a especificação passa por histórico, revisão e rollback como qualquer outro artefato do projeto.

Backup automático Git de especificações de API

O backup automático é diferente da sincronização. Ele envia arquivos OpenAPI/Swagger do Apidog para o Git em um agendamento, mas não lê alterações do repositório de volta para o Apidog.

Use esse modo quando você quer:

  • snapshots versionados da especificação;
  • histórico de alterações no Git;
  • restauração manual a partir do repositório;
  • backup sem exigir que a equipe edite YAML diretamente.

Funcionamento:

  1. Você configura o repositório de backup para um módulo.
  2. O Apidog exporta o arquivo OpenAPI/Swagger desse módulo.
  3. O sistema envia o arquivo para o repositório.
  4. O push ocorre em uma janela noturna aleatória fora do horário de pico.
  5. Cada envio gera histórico no Git.

Esse fluxo é unidirecional por design:

Apidog → Git
Enter fullscreen mode Exit fullscreen mode

Se você precisa do caminho inverso:

Git → Apidog
Enter fullscreen mode Exit fullscreen mode

use o Modo Spec-First.

Escolhendo branch e estrutura de repositório

Antes de conectar tudo, defina como as especificações serão organizadas.

Branch

Para a maioria das equipes:

  • main: especificação canônica e estável;
  • branches de feature: alterações em andamento;
  • pull requests: revisão antes do merge.

Exemplo:

main
feature/add-orders-api
feature/update-auth-errors
fix/pagination-schema
Enter fullscreen mode Exit fullscreen mode

Apontar o Apidog diretamente para main é mais simples, mas reduz controle de revisão. Prefira branches quando alterações de API precisam ser aprovadas.

Um repositório por API

Use quando:

  • APIs pertencem a equipes diferentes;
  • permissões precisam ser isoladas;
  • cada API tem ciclo de vida próprio.

Exemplo:

orders-api-spec
billing-api-spec
identity-api-spec
Enter fullscreen mode Exit fullscreen mode

Monorepo de especificações

Use quando:

  • uma equipe de plataforma mantém várias APIs;
  • você quer busca e revisão centralizadas;
  • os contratos precisam evoluir juntos.

Mantenha uma estrutura previsível:

api-specs/
  orders/
    openapi.yaml
  billing/
    openapi.yaml
  identity/
    openapi.yaml
Enter fullscreen mode Exit fullscreen mode

Se usar backups automáticos, dê a cada módulo um caminho próprio para evitar sobrescrita ou confusão no histórico.

Permissões de equipe e acesso

A integração depende de credenciais Git. Trate-as como parte da superfície de segurança do projeto.

No Apidog:

  • limite quem pode sincronizar;
  • permita push apenas para responsáveis pela especificação;
  • mantenha acesso de leitura para quem só precisa consultar.

No provedor Git:

  • GitHub e GitLab usam autorização OAuth do usuário;
  • Azure DevOps e conexões genéricas usam PAT;
  • PAT deve ser tratado como segredo;
  • escopo deve ser mínimo;
  • tokens devem ser rotacionados ou revogados quando necessário.

Regra prática:

Menor privilégio possível + propriedade clara do repositório
Enter fullscreen mode Exit fullscreen mode

Lidando com conflitos de merge

Conflitos acontecem quando duas pessoas alteram a mesma parte da especificação antes de sincronizar.

Exemplo de um conflito de merge Git em um arquivo YAML, mostrando alterações em dois lados diferentes antes da resolução.

Exemplo de cenário:

  1. Você altera o schema Order no Apidog.
  2. Um colega altera o mesmo schema no repositório.
  3. O colega faz push primeiro.
  4. Ao sincronizar, o Git detecta conflito no YAML.

Isso é um conflito Git normal, não um problema específico do Apidog.

Para reduzir conflitos:

  1. Faça pull antes de editar.
  2. Evite alterações grandes e pouco frequentes.
  3. Divida mudanças de API em commits menores.
  4. Use branches para trabalho em andamento.
  5. Revise diffs de schemas com atenção.

Ao resolver um conflito, mantenha o OpenAPI válido. O editor do Apidog ajuda com validação em tempo real, então problemas como $ref quebrado, indentação incorreta ou campo obrigatório ausente aparecem antes do push.

Solução de problemas

Sintoma Causa provável Como resolver
Autorização falha ou repositório não aparece Organização não aprovou o app, ou token sem escopo correto Peça aprovação ao administrador. Para Azure DevOps, gere um PAT com leitura/escrita em código.
Push rejeitado Token expirado, revogado ou sem escrita Reautorize o provedor ou atualize o PAT no Apidog.
Alterações enviadas não aparecem Branch incorreto Confira se o Apidog está conectado ao branch esperado.
Indicador de sincronização não atualiza Há alterações locais não enviadas ou pull pendente Faça commit/push ou puxe as alterações remotas antes de sincronizar.
Conflito de merge Duas alterações nas mesmas linhas do YAML Resolva o conflito manualmente, valide o OpenAPI e sincronize novamente.
Backup não executou Janela noturna ainda não ocorreu ou configuração incorreta Aguarde o próximo ciclo e confira repositório/branch configurados.
Alterações experimentais não devem ser mantidas Edições locais antes do commit Use a opção de descartar edições não enviadas.

Se algo “parou de funcionar”, comece por autenticação:

  • o token ainda existe?
  • o token expirou?
  • o escopo permite escrita?
  • a organização aprovou o app?
  • o branch conectado ainda existe?

FAQ

A sincronização é unidirecional ou bidirecional?

Depende do recurso usado.

O Modo Spec-First é bidirecional:

Apidog ↔ Git
Enter fullscreen mode Exit fullscreen mode

O backup automático é unidirecional:

Apidog → Git
Enter fullscreen mode Exit fullscreen mode

Onde minhas especificações são armazenadas?

No repositório Git conectado.

No Modo Spec-First, o documento OpenAPI vive no branch configurado. No backup automático, o arquivo OpenAPI/Swagger exportado de cada módulo é commitado no repositório definido.

Para qual branch devo sincronizar?

Use main para a versão canônica e branches separados para alterações em andamento. Isso permite revisar mudanças de API via pull request antes do merge.

O que acontece se meu token for revogado?

Os pushes falham porque o Apidog perde acesso de escrita. Reautorize GitHub/GitLab ou gere um novo PAT para Azure DevOps e conexões genéricas. Depois de restaurar a credencial, sincronização e backup voltam a funcionar.

Conclusão

A integração Git do Apidog cobre dois fluxos complementares:

  • Modo Spec-First para equipes que tratam OpenAPI como código;
  • backup automático Git para manter cópias versionadas das especificações.

Se você precisa de revisão, histórico e pull requests, configure a sincronização bidirecional. Se precisa apenas de durabilidade e rastreabilidade, configure o backup automático. Em muitos times, a melhor opção é usar os dois: edição controlada por Git e snapshots periódicos como rede de segurança.

Top comments (0)