Lucas

Posted on Aug 31 Originally published at apidog.com

Como conectar um repositório GHE.com ao Apidog

Como conectar o GitHub Enterprise Cloud com residência de dados ao Apidog

O Apidog pode se conectar a locatários de residência de dados do GitHub Enterprise Cloud hospedados em domínios dedicados *.ghe.com. Depois que um Administrador da Organização configura o locatário e o Aplicativo OAuth, usuários autorizados no projeto podem conectar repositórios e executar fluxos de importação, backup e sincronização OpenAPI.

Experimente o Apidog hoje

Esta integração atende apenas locatários SaaS de residência de dados do GitHub Enterprise Cloud. GitHub Enterprise Server e domínios GitHub personalizados arbitrários não são compatíveis.

Antes de começar

Você precisa de:

uma organização Apidog Enterprise com acesso à integração;
permissão de Administrador da Organização no Apidog;
um locatário de residência de dados do GitHub Enterprise Cloud em um domínio raiz *.ghe.com, como https://company.ghe.com;
permissão para criar um Aplicativo OAuth nesse locatário;
acesso às organizações, repositórios e branches que pretende conectar.

Os usuários que conectarem repositórios também precisam da permissão de conexão Git correspondente no nível do projeto Apidog.

1. Crie um Aplicativo OAuth no locatário GHE.com

Entre no locatário GHE.com da organização.
Abra as configurações de Aplicativos OAuth.
Crie um novo Aplicativo OAuth.
Informe um nome identificável.
Defina o URL da página inicial como https://apidog.com.
Defina o URL de retorno de autorização como https://api.apidog.com/passport/github/callback.
Registre o aplicativo.
Copie o Client ID.
Gere e armazene o Client Secret com segurança.

O URL de retorno deve corresponder exatamente ao URL documentado pelo Apidog.

Armazene o Client Secret no sistema aprovado de gerenciamento de segredos. Não o inclua em capturas de tela, tickets ou documentos compartilhados.

2. Configure o locatário GHE.com no Apidog

Somente um Administrador da Organização pode configurar ou limpar esta integração.

Abra a organização Apidog.
Acesse Configurações da Organização.
Abra Integração GitHub.
Localize Residência de Dados do GitHub Enterprise Cloud e selecione Configurar.

Informe o URL do host GHE.com, por exemplo https://company.ghe.com.
Selecione Aplicativo OAuth como método de autenticação.
Informe o Client ID.
Informe o Client Secret.
Salve a configuração.

Configure o host do locatário e as credenciais do Aplicativo OAuth no nível da organização.

Depois de salvar, o Apidog exibe o host configurado, mas não exibe nem preenche novamente o Client Secret.

Ao editar a configuração, deixe o campo Client Secret vazio para manter o segredo atual. Informe um novo valor somente durante a rotação.

3. Conecte um repositório a um projeto Apidog

Depois de concluir a configuração da organização:

Abra o projeto Apidog.
Inicie um fluxo de conexão Git ou importação Git.
Selecione GitHub Enterprise Cloud.
Continue até a página de autorização do locatário GHE.com configurado.
Entre e autorize o Aplicativo OAuth.
Selecione a organização GitHub, o repositório e a branch.
Conclua a conexão.

A autorização ocorre no locatário GHE.com configurado, não no github.com padrão.

Se a organização ou o repositório esperado não aparecer, verifique primeiro o acesso da conta GitHub e a autorização do Aplicativo OAuth. Evite alterar a configuração da organização Apidog antes dessas verificações.

4. Importe um arquivo OpenAPI

Para importar um arquivo OpenAPI ou Swagger do repositório conectado:

Inicie um fluxo de importação no projeto Apidog.
Escolha OpenAPI/Swagger.
Selecione Repositório Git.
Escolha a organização GitHub, o repositório, a branch e o arquivo.
Selecione Continuar.
Escolha um módulo de destino existente ou crie um novo.
Conclua a importação.
Revise os endpoints e esquemas antes de aceitar o resultado.

Selecione o repositório, a branch e o arquivo de especificação exigidos pelo projeto.

Use um projeto de não produção na primeira importação, especialmente quando o módulo de destino já contém definições de API.

5. Escolha o fluxo de sincronização

Defina uma fonte de verdade e documente-a para a equipe antes de automatizar a conexão.

Fluxo de trabalho	Use quando	Comportamento importante
Importação manual	As alterações só devem ser trazidas para o Apidog quando solicitado	Revise cada importação e o módulo de destino
Importação agendada	O arquivo Git é a fonte da verdade e o Apidog deve atualizá-lo periodicamente	Executa pelo cliente local ou por um Runner auto-hospedado, conforme o modo configurado
Backup para Git	O conteúdo do Apidog deve ser gravado em um arquivo do repositório	Configure repositório, branch e caminho; os backups automáticos ocorrem aleatoriamente durante um período noturno de pico
Modo Spec-first	A especificação é a fonte da verdade e a equipe trabalha por um fluxo orientado a Git	Atualmente está em beta; a instalação do webhook geralmente exige permissão de administrador do repositório

Não configure dois fluxos automatizados opostos para o mesmo arquivo sem definir uma regra de resolução de conflitos.

Configurar backup para Git

Crie ou selecione a conexão Git nas configurações do projeto.
Abra Visão Geral > Especificação da API do módulo.
Adicione ou selecione a especificação OpenAPI.
Ative Backup para Repositório Git.
Escolha a conexão, a branch e o caminho do arquivo de destino.
Salve a configuração.

Para uma fonte de verdade orientada por repositório, consulte a Importação Agendada ou o Modo Spec-first.

6. Verifique a integração

Execute um teste pequeno de ponta a ponta:

confirme que a autorização abre o locatário GHE.com configurado;
confirme que somente as organizações e os repositórios esperados aparecem;
importe um arquivo OpenAPI conhecido e compare o resultado com a fonte;
teste o backup ou a sincronização em uma branch descartável;
confirme o comportamento da proteção da branch e das permissões do repositório;
revise logs e erros de sincronização;
faça a rotação do Client Secret e confirme o processo documentado de atualização.

Se usar sincronização por webhook, confirme que o instalador tem permissão de administrador do repositório e que o evento de push esperado dispara a sincronização.

Atualizar ou limpar a configuração

Administradores da Organização podem editar o host ou o Client ID. Para rotacionar o Client Secret, informe um novo valor.

Para remover a configuração:

Abra Configurações da Organização > Integração GitHub.
Localize a integração de residência de dados.
Selecione Limpar configurações.

Depois da limpeza, os usuários não poderão criar novas conexões do GitHub Enterprise Cloud até que a integração seja configurada novamente. Conexões existentes podem exigir reconfiguração ou reautorização, dependendo do token e das configurações da organização.

Solução de problemas

Problema	O que verificar
A opção de integração está indisponível	Confirme o acesso Enterprise da organização e sua permissão de Administrador da Organização
O OAuth retorna erro de callback	Confirme que o callback é exatamente `https://api.apidog.com/passport/github/callback`
A autorização abre `github.com`	Confirme que o host da organização é o locatário raiz `*.ghe.com` correto
Um repositório está ausente	Verifique o acesso do usuário à organização e ao repositório e as restrições do OAuth
Um usuário não consegue criar uma conexão	Confirme a permissão de conexão Git no nível do projeto
A importação ou sincronização falha	Verifique branch, caminho do arquivo, formato, permissões do repositório e logs de sincronização

Limites de segurança e residência de dados

Somente Administradores da Organização podem configurar ou limpar a integração GHE.com.
O Client Secret não é exibido após a configuração.
As permissões do projeto continuam controlando quem pode criar ou atualizar conexões Git.
A autorização OAuth ocorre através do locatário GHE.com configurado.
As permissões OAuth podem incluir acesso para ler organizações, repositórios e branches, importar arquivos, gravar backups e gerenciar hooks quando o fluxo exigir.

Conectar um locatário de residência de dados não prova, por si só, que todas as categorias de dados relacionados ao GitHub ou ao Apidog permanecem em uma região específica. O GitHub documenta os dados cobertos por sua oferta e suas exceções. O Apidog é um serviço conectado separado, com seu próprio modelo de armazenamento e implantação. Para avaliações de residência de dados ou conformidade, consulte a documentação atual de ambos os fornecedores.

Tutoriais de governança de API relacionados

Estrutura de Governança de API — conecta propriedade, controles, evidências e decisões de ciclo de vida.
Mapeamento de Grupos SAML com Microsoft Entra ID — atribui acesso de equipe a partir de grupos do provedor de identidade.
Secret Scanner — revisa possíveis credenciais expostas em ativos Apidog compatíveis.
Logs de Auditoria — investiga e exporta atividades administrativas.
Provisionamento SCIM — gerencia usuários durante o ciclo de vida da identidade.
Políticas Empresariais — configura controles de credenciais, associações, sessões SSO e convites.
Equipes de API de Autoatendimento Governadas — permite equipes criadas por membros com supervisão de propriedade.
Integração com GitHub Enterprise Cloud — conecta repositórios GHE.com compatíveis a fluxos OpenAPI.

DEV Community