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 de projeto autorizados podem conectar repositórios e usar fluxos de trabalho de importação, backup e sincronização OpenAPI compatíveis.
Esta integração é para locatários SaaS de residência de dados do GitHub Enterprise Cloud. Ela não oferece suporte ao GitHub Enterprise Server ou a domínios GitHub personalizados arbitrários.
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
- de um locatário de residência de dados do GitHub Enterprise Cloud em um domínio raiz
*.ghe.com, comohttps://company.ghe.com - permissão para criar um Aplicativo OAuth nesse locatário
- acesso às organizações, repositórios e branches do GitHub que você planeja conectar
Os usuários que conectam repositórios também devem ter a permissão de conexão Git de nível de projeto relevante no Apidog.
Etapa 1: Crie um Aplicativo OAuth no locatário GHE.com
- Faça login no locatário GHE.com da sua organização.
- Abra as configurações de Aplicativos OAuth.
- Crie um novo Aplicativo OAuth.
- Insira um nome de aplicativo 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 OAuth.
- Copie o Client ID (ID do Cliente).
- Gere e copie com segurança o Client Secret (Segredo do Cliente).
O URL de retorno deve corresponder exatamente ao URL do Apidog documentado.
Armazene o Segredo do Cliente em seu sistema aprovado de gerenciamento de segredos. Não o coloque em uma captura de tela, ticket ou documento compartilhado.
Etapa 2: Configure o locatário GHE.com no Apidog
Apenas um Administrador da Organização pode configurar ou limpar esta integração.
- Abra a organização Apidog.
- Vá para Configurações da Organização.
- Abra Integração GitHub.
- Encontre Residência de Dados do GitHub Enterprise Cloud e selecione Configurar.
- Insira o URL do host GHE.com, por exemplo
https://company.ghe.com. - Selecione Aplicativo OAuth como método de autenticação.
- Insira o ID do Cliente do Aplicativo OAuth.
- Insira o Segredo do Cliente do Aplicativo OAuth.
- Salve a configuração.
Configure o host do locatário e as credenciais do Aplicativo OAuth no nível da organização.
Após salvar, o Apidog exibe o URL do host configurado. O Segredo do Cliente não é exibido ou preenchido novamente.
Ao editar a configuração posteriormente, deixar o campo Segredo do Cliente vazio mantém o segredo existente. Insira um novo valor apenas ao rotacioná-lo.
Etapa 3: Conecte um repositório a partir de um projeto Apidog
Após a conclusão da configuração no nível da organização:
- abra o projeto Apidog necessário;
- inicie um fluxo de trabalho de conexão Git ou importação Git;
- selecione GitHub Enterprise Cloud;
- prossiga para a página de autorização no locatário GHE.com configurado;
- faça login e autorize o Aplicativo OAuth;
- selecione a organização GitHub;
- selecione o repositório e a branch;
- conclua a conexão.
A autorização é realizada no locatário GHE.com configurado, não no github.com padrão.
Se a organização ou repositório esperado estiver faltando, verifique o acesso da conta GitHub e a autorização do Aplicativo OAuth antes de alterar as configurações da organização Apidog.
Etapa 4: Importar um arquivo OpenAPI
Para importar um arquivo OpenAPI ou Swagger do repositório conectado:
- inicie um fluxo de trabalho de importação no projeto Apidog;
- escolha OpenAPI/Swagger;
- selecione Repositório Git;
- escolha a organização GitHub, repositório, branch e arquivo;
- selecione Continuar;
- escolha um Módulo de destino existente ou crie um novo;
- conclua a importação;
- revise os endpoints e esquemas importados antes de aceitar o resultado.
Selecione o repositório, branch e arquivo de especificação exigidos pelo projeto.
Use um projeto não-produção para a primeira importação, especialmente quando o módulo de destino já contém definições de API.
Etapa 5: Escolha o fluxo de trabalho de sincronização contínua
A conexão do repositório pode suportar diferentes fluxos de trabalho. Escolha uma fonte de verdade e documente-a para a equipe.
| Fluxo de trabalho | Use quando | Comportamento importante |
|---|---|---|
| Importação Manual | As alterações são trazidas para o Apidog apenas quando solicitado | Revise cada importação e módulo de destino |
| Importação Agendada | O arquivo Git permanece como a fonte e o Apidog deve atualizá-lo em um intervalo | Executa através do cliente local ou de um Runner auto-hospedado de acordo com o modo de execução configurado |
| Backup para Git | O conteúdo do Apidog deve ser gravado em um arquivo de repositório | Configure o repositório, a branch e o caminho do arquivo de destino; backups automáticos são executados durante um período de pico aleatoriamente agendado à noite |
| Modo Spec-first | O arquivo de especificação é a fonte da verdade e a equipe edita através de um fluxo de trabalho orientado a Git | Este modo está atualmente em beta; a instalação do webhook geralmente requer permissão de administrador do repositório |
Não configure dois fluxos de trabalho automatizados opostos para o mesmo arquivo sem uma regra clara de resolução de conflitos.
Para backup:
- crie ou selecione a conexão Git nas configurações do projeto;
- abra a seção Visão Geral > Especificação da API do módulo;
- adicione ou selecione a especificação OpenAPI;
- habilite Backup para Repositório Git;
- escolha a conexão do repositório, a branch e o caminho do arquivo de destino;
- salve a configuração.
Para uma fonte de verdade orientada por repositório, use a Importação Agendada ou revise o Modo Spec-first.
Etapa 6: Verifique a integração
Execute um pequeno teste de ponta a ponta:
- confirme se a autorização abre o locatário GHE.com configurado
- confirme se apenas as organizações e repositórios esperados estão disponíveis
- importe um arquivo OpenAPI conhecido e compare o resultado com a fonte
- teste a direção de backup ou sincronização selecionada em uma branch descartável
- confirme se a proteção da branch e as permissões do repositório se comportam conforme o esperado
- revise os logs ou erros de sincronização
- rotacione o Segredo do Cliente do Aplicativo OAuth e confirme se o processo de atualização documentado funciona
Se a sincronização via webhook for usada, verifique se o instalador tem permissão de administrador do repositório e se o evento de push esperado aciona a sincronização.
Atualizar ou limpar as configurações da organização
Administradores da Organização podem editar o URL do host ou o ID do Cliente e podem rotacionar o Segredo do Cliente inserindo um novo valor.
Para remover a configuração no nível da organização, abra Configurações da Organização > Integração GitHub, encontre a integração de residência de dados e selecione Limpar configurações.
Depois que as configurações são limpas, os usuários não podem criar novas conexões do GitHub Enterprise Cloud até que a integração seja configurada novamente. As conexões existentes podem exigir reconfiguração ou reautorização dependendo do status 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 se a organização tem acesso ao recurso Enterprise e se você é um Administrador da Organização. |
| O OAuth retorna um erro de retorno de chamada | Confirme se o retorno de chamada do Aplicativo OAuth é exatamente https://api.apidog.com/passport/github/callback. |
| A autorização abre github.com | Confirme se o host no nível da organização é o locatário raiz *.ghe.com pretendido. |
| Um repositório está faltando | Verifique o acesso da organização e do repositório do usuário GitHub autorizado e quaisquer restrições do OAuth. |
| Um usuário do projeto não consegue criar uma conexão | Confirme se o usuário tem a permissão de conexão Git de nível de projeto necessária. |
| Falha na importação ou sincronização | Verifique a branch selecionada, o caminho do arquivo, o formato do arquivo, as permissões do repositório e os logs de sincronização. |
Limites de segurança e residência de dados
- Apenas Administradores da Organização podem configurar ou limpar a integração GHE.com.
- O Segredo do Cliente não é exibido após a configuração.
- As permissões do projeto ainda controlam 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 solicitadas podem incluir acesso necessário para ler organizações, repositórios, branches, importar arquivos, gravar backups e gerenciar hooks de repositório quando exigido por um fluxo de trabalho de sincronização.
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 Apidog permanecem em uma região. O GitHub documenta os dados cobertos por sua oferta de residência e as exceções relevantes. O Apidog é um serviço conectado separado com seu próprio modelo de armazenamento e implantação. Revise a documentação atual de ambos os fornecedores como parte de uma avaliação de residência de dados ou conformidade.
Tutoriais de governança de API relacionados:
Estes tutoriais cobrem controles complementares para governar um espaço de trabalho de API empresarial:
- 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 de provedores de identidade.
- Secret Scanner — revisa possíveis credenciais expostas em ativos Apidog compatíveis.
- Logs de Auditoria — investiga e exporta atividades administrativas da organização.
- Provisionamento SCIM — gerencia usuários da organização através do 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, mantendo a supervisão da propriedade.
- Integração com GitHub Enterprise Cloud — conecta repositórios GHE.com compatíveis para fluxos de trabalho OpenAPI.
Documentação oficial relacionada: