> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Conectores
> Configure conectores locais para acessar VCS privados, self-hosted ou restritos à rede da organização.
Conectores permitem que a Acrity trabalhe com provedores de código que não devem ser acessados diretamente pela nuvem da Acrity.
Use `Console > Conectores` para criar um conector, gerar segredos de instalação, baixar artefatos de implantação, acompanhar atividade e associar repositórios.
Conectores exigem um Admin de workspace. As funções são conjuntos fixos de capacidades definidos pela Acrity, portanto nenhuma outra função pode criar, editar ou revalidar um conector.
## Quando usar
Use conectores quando:
* o VCS está em rede privada;
* o provedor é self-hosted;
* o acesso ao VCS precisa sair de uma rede controlada pela organização;
* políticas internas impedem que tokens de VCS sejam armazenados em serviços externos;
* você precisa atravessar proxy corporativo ou CA privada.
Para provedores SaaS com instalação oficial, avalie primeiro `Console > Aplicativos conectados`.
## Como funciona em alto nível
1. Um Admin de workspace cria o conector no Console.
2. O Console exibe segredos de instalação uma única vez.
3. A equipe instala o componente local no ambiente da organização.
4. O conector abre uma conexão de saída apenas de egress para a Acrity e alcança o VCS privado localmente.
5. Repositórios passam a ser descobertos e associados pelo Console.
A nuvem da Acrity não mantém nenhuma credencial do VCS. Apenas o conector local, em execução dentro da sua rede, mantém as credenciais do seu VCS privado. O conector abre uma conexão de saída segura, apenas de egress, para a Acrity, portanto você não precisa abrir nenhuma porta de entrada na sua rede.
```mermaid theme={null}
flowchart LR
subgraph customer["Rede do cliente"]
vcs["VCS privado"]
connector["Conector local
(mantém as credenciais locais do VCS)"]
end
subgraph acrity["Nuvem da Acrity"]
broker["Broker / gateway
(não mantém credenciais do VCS)"]
engine["Motor de review"]
end
vcs -- "evento de PR / MR se origina aqui" --> connector
connector -- "conexão de saída segura, apenas de egress
(sem portas de entrada)" --> broker
broker --> engine
```
Detalhes de segurança, retenção e tratamento de dados ficam em `Segurança > Tratamento de dados` e `Segurança > Credenciais e tokens`.
## Criar um conector
Acesse `Console > Conectores`.
Escolha criar um novo conector.
Preencha nome, provedor e URL base da instância quando aplicável.
Gere o token do conector e o segredo de relay quando solicitado.
Copie e armazene os valores em um cofre seguro. Eles são exibidos apenas uma vez.
Baixe o formato de instalação compatível com o ambiente da organização.
Instale o conector, aguarde o heartbeat e execute Revalidar quando disponível.
O token do conector é armazenado pela Acrity apenas como um hash SHA-256. Como a Acrity não mantém nenhuma cópia recuperável do segredo, ele nunca pode ser exibido novamente após a criação. Se você perdê-lo, gere um novo token e atualize a instalação local.
## Campos principais
| Campo | Para que serve |
| ---------------------- | ----------------------------------------------------------------------------------------------- |
| Nome | Identifica o conector no Console. |
| Provedor | Define o tipo de VCS ou integração atendida pelo conector. |
| URL base da instância | Endereço da instalação self-hosted ou organização quando necessário. |
| Token do conector | Segredo usado pelo componente local para se identificar. Exibido uma única vez. |
| Segredo de relay | Segredo usado para proteger a conexão de saída do conector com a Acrity. Exibido uma única vez. |
| Formato de implantação | Pacote ou manifesto usado para instalar o conector no ambiente local. |
## Estados de saúde
O Console exibe um estado de saúde para cada conector, com base no heartbeat e na Revalidação mais recente.
| Estado | Significado |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Conectado | O conector está comunicando normalmente e alcançando o VCS. |
| Degradado | O conector responde, mas com uma limitação ou falha parcial (por exemplo, respostas lentas ou um subconjunto de repositórios inacessível). |
| Offline | A Acrity não recebeu comunicação recente do conector. |
| Erro | Há uma falha que exige correção de configuração, rede ou credenciais locais. |
Use **Revalidar** para forçar uma verificação imediata de conectividade e credenciais em vez de aguardar o próximo heartbeat automático. Depois de corrigir um problema, execute Revalidar para confirmar que o conector volta ao estado conectado.
## Baixar artefato de instalação
Depois de criar o conector:
1. Acesse `Console > Conectores`.
2. Abra o conector.
3. Escolha o formato de implantação suportado pela sua infraestrutura.
4. Baixe o artefato.
5. Entregue o pacote à equipe responsável pela instalação local.
Não publique artefatos com segredos em repositórios compartilhados. Trate arquivos de configuração como material sensível.
## Associar repositórios
Quando o conector estiver online:
1. Acesse `Console > Repositórios > Conectar repositório`.
2. Escolha o conector como origem de acesso ao VCS.
3. Selecione ou informe os repositórios desejados.
4. Complete as configurações de branch, PM e review.
5. Salve e valide o status do repositório.
## Rotacionar segredos
Rotacione segredos quando:
* alguém com acesso ao segredo saiu da equipe;
* houve suspeita de exposição;
* a política interna exige rotação periódica;
* o ambiente local foi recriado;
* o conector será movido para outra infraestrutura.
Após gerar novos segredos, atualize a instalação local e execute Revalidar para confirmar que o conector voltou ao estado conectado.
## Problemas comuns
| Sintoma | O que verificar |
| ------------------------- | ----------------------------------------------------------------------------- |
| Conector offline | Verifique instalação local, rede, proxy, DNS, firewall e segredo configurado. |
| Revalidação falha | Confirme URL base, credenciais locais e acesso do conector ao VCS. |
| Repositórios não aparecem | Verifique permissões no VCS, escopo do conector e atualização da lista. |
| Perdi o token exibido | Gere um novo token e atualize a instalação local. |
| Erro de certificado | Confirme CA corporativa e configuração TLS do ambiente local. |
## Boas práticas
* Instale conectores em infraestrutura administrada pela organização.
* Guarde segredos em cofre seguro.
* Use contas de serviço com escopo mínimo.
* Monitore heartbeat e alertas do Console.
* Revogue conectores não utilizados.
* Documente internamente quem opera cada conector.