> ## Documentation Index
> Fetch the complete documentation index at: https://zeropath.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com GitHub Enterprise Server

> Conecte uma instância auto-hospedada do GitHub Enterprise Server ao ZeroPath para scans, verificações de PR, comentários e pull requests de correção

<h2 id="overview">
  Visão geral
</h2>

O ZeroPath se conecta a instâncias auto-hospedadas do **GitHub Enterprise Server (GHES)** por meio de um GitHub App
que você cria na sua própria instância. Uma vez conectado, você pode importar repositórios, executar scans completos,
escanear pull requests, publicar verificações de status e comentários inline, abrir pull requests de correção para
achados validados e visualizar achados de dependências no painel [Supply Chain](/pt/sca/overview). Essas são
as mesmas funcionalidades que o ZeroPath oferece para o GitHub.com.

A conexão é configurada com o [fluxo de App Manifest](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest) do GitHub:
você insere a URL da sua instância no ZeroPath, revisa o app na sua instância e confirma a sua
criação. O ZeroPath recebe as credenciais do app da sua instância, armazena-as criptografadas e
instala o app nas organizações que você escolher. Você nunca copia um client secret ou uma chave privada
manualmente.

<Note>
  Apps do GHES são isolados por instância. Cada instância que você conecta recebe seu próprio registro de app e
  suas próprias credenciais criptografadas, então conectar uma instância nunca afeta outra, e nunca
  interfere na sua conexão com o GitHub.com.
</Note>

<h2 id="prerequisites">
  Pré-requisitos
</h2>

* Uma organização no ZeroPath onde você possa criar instalações de VCS e repositórios.
* Uma instância do GitHub Enterprise Server que seja:
  * acessível pelo ZeroPath via **HTTPS** (HTTP simples é rejeitado), e
  * resolvível por **DNS público**.
* Permissão na instância para **criar um GitHub App** (via fluxo de App Manifest) e para **instalar
  o app** na organização de destino. Se você não puder instalar apps diretamente, sua solicitação de
  instalação é enviada a um proprietário da organização para aprovação.
* A capacidade de atualizar sua lista de permissões de rede / firewall para que os IPs de saída do ZeroPath alcancem sua
  instância, e para que sua instância consiga entregar webhooks de volta ao ZeroPath. Consulte
  [Rede e firewall](#network-and-firewall).

<h2 id="connect-github-enterprise-server">
  Conecte o GitHub Enterprise Server
</h2>

<Steps>
  <Step title="Abra a configuração do GitHub Enterprise Server">
    No ZeroPath, acesse [Add Repositories](https://zeropath.com/app/repositories?m=AddRepos\&tab=ghes),
    selecione a aba **GitHub Enterprise Server** e abra o diálogo de configuração.
  </Step>

  <Step title="Libere o ZeroPath no seu firewall">
    O diálogo de configuração lista os IPs de origem de saída do ZeroPath. Adicione-os à sua lista de permissões de rede para que
    o ZeroPath possa alcançar a API REST/GraphQL da sua instância, clonar repositórios, e para que sua instância possa
    entregar webhooks ao ZeroPath.

    <Note>
      Se a lista de IPs de saída não for exibida no seu ambiente, entre em contato com o
      [suporte do ZeroPath](mailto:support@zeropath.com) para obter os IPs de origem atuais antes de continuar.
    </Note>
  </Step>

  <Step title="Insira a URL da sua instância">
    Insira a URL do seu GitHub Enterprise Server, por exemplo `https://github.your-company.com`. A URL
    deve ser uma origem HTTPS que resolva por DNS público. O ZeroPath rejeita `github.com` e seus
    aliases, bem como hosts que resolvem para endereços privados, de loopback ou link-local.
  </Step>

  <Step title="Escolha como o ZeroPath confia no seu certificado TLS">
    * **Publicly-trusted certificate** - o padrão. Você não precisa fornecer mais nada.
    * **Internal / self-signed** - cole ou envie seu bundle de CA em formato PEM. O ZeroPath o armazena
      criptografado e o usa apenas para verificar o TLS da sua instância. O ZeroPath sempre verifica
      certificados; ele nunca desabilita a validação.
  </Step>

  <Step title="Crie o app na sua instância">
    Clique em **Create app on your GitHub Enterprise**. O ZeroPath envia você para a sua instância para criar o
    GitHub App `zeropath-scanner`. Revise as permissões e eventos solicitados (consulte
    [O que o app pode acessar](#what-the-app-can-access)) e então confirme em **Create GitHub App**.

    <Note>
      O handshake de manifest do GitHub é válido por uma hora e pode ser usado uma única vez. Se você demorar demais ou
      sair da página, reinicie o fluxo a partir do diálogo de configuração.
    </Note>
  </Step>

  <Step title="Instale o app na sua organização">
    Depois que o app é criado, o ZeroPath envia você para a página de instalação de apps da sua instância. Selecione a
    organização cujos repositórios você quer escanear e aprove a instalação.

    <Note>
      Se você não tiver permissão para instalar o app, sua solicitação é enviada a um proprietário da organização
      para aprovação. Os repositórios aparecem assim que o proprietário a aprovar.
    </Note>
  </Step>

  <Step title="Aguarde a sincronização">
    Você é redirecionado de volta ao ZeroPath, e seus repositórios do GHES começam a sincronizar. Eles aparecem em
    **Accessible repositories** quando estiverem prontos.
  </Step>

  <Step title="Adicione repositórios">
    Selecione quais repositórios adicionar ao ZeroPath ou clique em **Add All**.
  </Step>
</Steps>

<h2 id="what-the-app-can-access">
  O que o app pode acessar
</h2>

O ZeroPath cria o app com o mesmo conjunto de permissões e eventos do seu GitHub App oficial, para que
o scanning se comporte de forma idêntica no GitHub.com e no GitHub Enterprise Server.

O app solicita estas **permissões**:

| Permissão                                           | Acesso  | Por quê                                                   |
| --------------------------------------------------- | ------- | --------------------------------------------------------- |
| Metadata                                            | Leitura | Acesso básico ao repositório                              |
| Contents                                            | Escrita | Clonar código; enviar branches de correção                |
| Pull requests                                       | Escrita | Escanear PRs, publicar comentários, abrir PRs de correção |
| Checks                                              | Escrita | Publicar verificações de status em PRs                    |
| Issues                                              | Escrita | Fluxos de trabalho baseados em issues e comentários       |
| Administration                                      | Leitura | Enumerar os repositórios de uma organização               |
| Members                                             | Leitura | Resolver a composição de membros da organização           |
| Merge queues                                        | Leitura | Necessário para receber webhooks `merge_group`            |
| Organization & repository custom properties / roles | Leitura | Classificação e roteamento de repositórios                |

O app se inscreve nestes **eventos de webhook**: `push`, `pull_request`, `pull_request_review`,
`pull_request_review_comment`, `pull_request_review_thread`, `issues`, `issue_comment`,
`merge_group`, `member`, `membership`, `organization`, `repository`, `team`, `team_add` e
`custom_property_values`.

<h2 id="network-and-firewall">
  Rede e firewall
</h2>

A conexão precisa de tráfego em **ambas** as direções:

* **Do ZeroPath para a sua instância (saída do ZeroPath).** O ZeroPath chama as APIs REST e
  GraphQL da sua instância (em `https://<your-host>/api/v3` e `https://<your-host>/api`), clona
  repositórios e conclui os handshakes de manifest e OAuth. Tudo isso se origina dos
  IPs de saída do ZeroPath exibidos no diálogo de configuração. Adicione-os à lista de permissões no firewall da sua instância.
* **Da sua instância para o ZeroPath (entrada no ZeroPath).** Sua instância entrega eventos de webhook ao
  endpoint público do ZeroPath. Sua instância deve conseguir alcançar o ZeroPath pela internet pública
  para que scans de PR e atualizações de repositórios sejam acionados.

<Warning>
  O ZeroPath deve alcançar sua instância via HTTPS em um nome DNS resolvível publicamente. Instâncias que são
  acessíveis apenas em uma rede privada, ou cujo hostname resolve para um endereço privado ou de loopback,
  não podem ser conectadas. Isso é aplicado como uma salvaguarda anti-SSRF.
</Warning>

<h3 id="tls-certificates">
  Certificados TLS
</h3>

Se a sua instância apresenta um certificado com confiança pública, nenhuma configuração extra é necessária. Se ela
usa um certificado interno ou autoassinado, forneça o bundle de CA (PEM) durante a configuração. O ZeroPath
armazena o bundle criptografado e confia nele apenas para conexões com a sua instância. Ele não altera
nenhum repositório de confiança global, e a verificação de certificados permanece habilitada o tempo todo.

<h2 id="repository-imports">
  Importação de repositórios
</h2>

O ZeroPath descobre repositórios a partir das organizações onde o app está instalado. Importe-os da
mesma forma que nos outros provedores:

* **Repositório único** - selecione um repositório e adicione-o.
* **Lote selecionado** - selecione vários repositórios e importe-os juntos.
* **Adicionar todos** - importe todos os repositórios acessíveis de uma vez.

Repositórios importados recebem as mesmas configurações padrão de scanner, tags, limites de repositórios, eventos de
auditoria e notificações de repositório adicionado que os demais provedores de VCS suportados.

<h2 id="pr-scanning">
  Scan de PRs
</h2>

Quando um pull request é aberto ou atualizado em um repositório conectado, sua instância entrega um webhook
ao ZeroPath, que agenda um scan de PR sobre os arquivos alterados. Os resultados podem incluir:

* Uma verificação de status do ZeroPath no pull request.
* Comentários de revisão inline nas linhas de diff afetadas.
* Um comentário de resumo no PR com o resultado do scan.
* Resolução automática de threads de comentários obsoletas quando os achados são corrigidos ou triados.

Os [comandos do bot](/pt/scanning/bot-commands) funcionam em comentários de pull requests do GHES da mesma forma que no
GitHub.com.

<h2 id="patch-pull-requests">
  Pull requests de correção
</h2>

Quando um achado é elegível para uma correção automática, o ZeroPath pode abrir um pull request na sua instância
usando o mesmo fluxo de correção dos outros provedores:

* Gerar um branch de correção.
* Fazer o commit da correção com a convenção padrão de mensagens de commit do ZeroPath.
* Abrir um pull request direcionado ao branch original.
* Adicionar contexto de resumo e vincular o PR de correção de volta ao achado no ZeroPath.

<h2 id="multiple-organizations-and-reconnecting">
  Múltiplas organizações e reconexão
</h2>

* **Múltiplas organizações em uma instância** - o app `zeropath-scanner` pode ser instalado em várias
  organizações da sua instância. Instale-o em cada organização cujos repositórios você quer
  escanear.
* **Reconexão** - se você iniciar a configuração novamente para uma instância que o ZeroPath já registrou, ele
  pula a criação do app e envia você direto para a página de instalação. Se o app anterior foi excluído
  na sua instância, o ZeroPath registra um novo.

<h2 id="troubleshooting">
  Solução de problemas
</h2>

<AccordionGroup>
  <Accordion title="O ZeroPath rejeita a URL da minha instância">
    A URL deve ser HTTPS e resolver por DNS público. `github.com` e seus aliases são rejeitados, assim
    como hosts que resolvem para endereços privados, de loopback, link-local ou de NAT de nível de operadora. Confirme
    que sua instância tem um nome DNS público e um endpoint HTTPS acessível.
  </Accordion>

  <Accordion title="Erros de TLS / certificado durante a configuração">
    Se a sua instância usa um certificado interno ou autoassinado, escolha **Internal / self-signed**
    e forneça a cadeia de CA completa em formato PEM. Uma cadeia parcial (sem os intermediários) é a causa mais
    comum de falhas de verificação.
  </Accordion>

  <Accordion title="O app foi criado, mas nenhum repositório aparece">
    O app deve ser **instalado** em uma organização, não apenas criado. Conclua a etapa de instalação
    e selecione a organização de destino. Se você não tem permissão de instalação, um proprietário da organização deve
    aprovar a solicitação pendente antes que os repositórios sincronizem.
  </Accordion>

  <Accordion title="'Create GitHub App' falha ou o fluxo expira">
    O handshake de manifest do GitHub expira uma hora após o início e é de uso único. Reinicie a configuração
    a partir da aba GitHub Enterprise Server para obter um novo handshake.
  </Accordion>

  <Accordion title="Scans de PR ou atualizações de repositórios não são acionados">
    Os eventos de webhook são entregues da sua instância para o endpoint público do ZeroPath. Confirme que sua
    instância consegue alcançar a internet pública e que nenhum firewall de saída está bloqueando a entrega de webhooks.
    Confirme também que o scan de PR está habilitado nas configurações do repositório no ZeroPath.
  </Accordion>

  <Accordion title="Status, comentários ou PRs de correção não aparecem">
    Isso requer que as permissões de escrita do app (checks, pull requests, contents) permaneçam concedidas na
    organização de destino. Confirme que a instalação ainda possui essas permissões e que as regras de proteção
    de branch na sua instância não estão bloqueando atualizações automatizadas de branches.
  </Accordion>
</AccordionGroup>

<h2 id="operational-notes">
  Notas operacionais
</h2>

* Desconectar uma instalação do GHES impede que novos scans sejam agendados para aquela conexão e
  remove os repositórios vinculados por meio dela. Repositórios protegidos pelo modo pesquisador são retidos
  até que o modo pesquisador seja desabilitado.
* Se você adicionar novas organizações após a configuração, instale o app nelas para que o ZeroPath possa descobrir seus
  repositórios.
* Apps e credenciais do GHES têm escopo por instância e são armazenados criptografados; conectar ou
  desconectar uma instância não afeta nenhuma outra instância nem a sua conexão com o GitHub.com.