> ## 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.
# Repositórios
> Conecte repositórios, configure revisão, PM, branch rules, webhooks de VCS e bootstrap de arquitetura.
Repositórios são o centro operacional da Acrity. Eles definem como pull requests ou merge requests são analisados, quais provedores são usados e quais exceções se aplicam a cada projeto.
Use `Console > Repositórios` para listar, conectar, configurar, pausar, validar e remover repositórios.
Acompanhe status de revisão, decisões e achados no painel de Ops. Use `Console > Audit Trail` apenas para detalhes técnicos de eventos, diagnóstico e auditoria administrativa.
## Quem pode acessar
Repositórios exigem um admin de workspace. Os papéis são conjuntos fixos de capacidades definidos pela Acrity, não configuráveis pela sua organização.
## Conectar repositórios
Acesse `Console > Repositórios > Conectar repositório`.
Selecione aplicativo conectado, credencial manual ou conector local.
Escolha os repositórios disponíveis ou informe os nomes conforme a origem escolhida.
Opcionalmente associe provedor de gerenciamento de tarefas e campos de extração.
Configure branches, comportamento para drafts, checks e idioma quando necessário.
Salve e acompanhe o status de prontidão na lista ou no detalhe do repositório.
## Métodos de conexão
| Método | Quando usar |
| -------------------- | ---------------------------------------------------------------------- |
| Aplicativo conectado | Provedor SaaS com instalação autorizada no workspace. |
| Credencial manual | Token ou credencial específica controlada pelo workspace. |
| Conector local | VCS privado, self-hosted ou acessível apenas pela rede da organização. |
## Estados de prontidão
Um repositório precisa alcançar o estado **Pronto** antes que a Acrity analise seus pull requests ou merge requests. Acompanhe o estado atual na lista de repositórios e na página de detalhe do repositório.
O bootstrap do `ARCHITECTURE.md` é obrigatório, não opcional. Até ser mesclado, o repositório permanece em **Aguardando merge da arquitetura** e não recebe revisões.
| Estado | Significado | Como avançar |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Pronto | A conexão está autorizada, o webhook de entrada é válido e o `ARCHITECTURE.md` foi mesclado. A Acrity revisa novos PRs/MRs. | Nenhuma ação necessária. Mantenha a conexão e o webhook saudáveis. |
| Aguardando merge da arquitetura | A conexão e o webhook são válidos, mas o repositório ainda precisa da sua baseline de arquitetura. O bootstrap do `ARCHITECTURE.md` é obrigatório e condiciona a prontidão. | Abra a aba Bootstrap, gere a documentação de arquitetura e faça o merge do `ARCHITECTURE.md` na branch alvo. |
| Configuração incompleta | Falta configuração obrigatória, como o webhook de entrada, a credencial ou a seleção de conector. | Conclua as etapas de Conectar repositório: confirme a origem, cole a URL e a chave do webhook de entrada no provedor e revalide. |
| Bloqueado | A Acrity não consegue acessar o repositório. A credencial, o aplicativo conectado ou o conector falhou na validação, ou as permissões foram revogadas. | Corrija ou rotacione a credencial, reautorize o aplicativo conectado ou revalide o conector e, em seguida, confirme as permissões. |
```mermaid theme={null}
stateDiagram-v2
state "Configuração incompleta" as Setup
state "Bloqueado" as Blocked
state "Aguardando merge da arquitetura" as Awaiting
state "Pronto" as Ready
[*] --> Setup: Repositório conectado
Setup --> Blocked: Falha na validação
Setup --> Awaiting: Conexão e webhook válidos
Blocked --> Awaiting: Credencial ou conector corrigido
Awaiting --> Ready: ARCHITECTURE.md mesclado
Ready --> Blocked: Acesso revogado
Ready --> [*]: Repositório removido
```
## Tela de lista
A lista de repositórios ajuda a identificar:
* repositórios conectados;
* estado de prontidão;
* provedor VCS;
* método de autenticação;
* última validação;
* alertas de webhook, credencial ou conector;
* repositórios que exigem ação antes de receber revisões.
Use filtros e busca para localizar projetos rapidamente. A lista de repositórios pode mostrar dicas operacionais, mas o painel de Ops é o lugar principal para acompanhar o progresso e os resultados das revisões.
## Detalhe do repositório
A página de detalhe concentra as configurações do projeto.
| Aba ou seção | Para que serve |
| ------------- | ---------------------------------------------------------------------------------------- |
| Configurações | Dados gerais, provedor, autenticação, idioma, pausa de reviews e estado operacional. |
| PM | Campos e fontes usados para associar PRs/MRs a tarefas, critérios e contexto de produto. |
| Review | Tiers e instruções adicionais específicas do repositório. |
| Bootstrap | Fluxo assistido para preparar ou revisar documentação de arquitetura do repositório. |
## Idioma do repositório
O idioma do repositório sobrescreve o padrão do workspace para aquele projeto.
Use quando:
* uma equipe trabalha em idioma diferente do restante do workspace;
* repositórios de clientes exigem respostas localizadas;
* comentários de revisão precisam seguir padrão de comunicação específico.
Se não houver idioma configurado no repositório, a Acrity usa o padrão do workspace.
## Regras de branch
Regras de branch ajudam a evitar revisões em cenários que não precisam de análise ou que geram ruído.
Configurações comuns:
* branches raiz ou principais, como `main`, `master`, `develop` ou equivalentes;
* ignorar merges entre branches raiz;
* regras para ignorar combinações específicas de origem e destino;
* correspondência por texto exato, prefixo, sufixo, trecho ou padrão configurado;
* revisão de PR/MR em draft;
* comportamento quando checks do provedor indicam sucesso.
Comece com regras conservadoras. Depois ajuste com base no volume real de revisões e nos casos que geraram ruído.
## Integração com PM
A integração de PM permite que a Acrity relacione PRs/MRs a tarefas, critérios de aceite e contexto de produto.
Campos comuns:
* identificador da tarefa;
* critérios de aceite;
* story points;
* sprint;
* épico;
* prioridade;
* componente;
* labels;
* campo de fallback quando a informação principal não está disponível.
Fontes comuns para extração:
* nome da branch;
* título do PR/MR;
* descrição do PR/MR;
* comentários quando habilitados pela configuração.
## Configuração de review por repositório
A configuração do repositório deve ser usada para exceções ao padrão do workspace.
Use quando:
* um projeto exige instruções diferentes;
* um repositório precisa de apenas um tier de revisão;
* a equipe tem convenções específicas;
* a saída de revisão deve usar linguagem ou foco diferente.
Evite duplicar no repositório o que já está bem definido no `Console > Policy Engine`.
## Pausar e retomar reviews
Pausar reviews impede novas análises automáticas para o repositório enquanto a pausa estiver ativa.
Use pausa quando:
* o repositório está em migração;
* o provedor está instável;
* credenciais estão sendo rotacionadas;
* a equipe quer interromper revisões por uma janela planejada;
* regras precisam ser revisadas antes de continuar.
Retome assim que a causa for resolvida.
## Webhook de VCS
O webhook de VCS permite que eventos do provedor acionem a Acrity.
Pelo Console, você pode:
* configurar webhook quando o provedor e método de conexão permitirem;
* revalidar webhook;
* revisar status de configuração;
* identificar pendências de permissão ou segredo.
Se o provedor for acessado por conector local, siga também a documentação de `Console > Conectores`.
## Como as revisões são disparadas
A Acrity inicia uma revisão quando o seu provedor envia um evento de pull request ou merge request para o webhook de VCS de entrada da Acrity.
Para conexões via aplicativo conectado, a Acrity registra o webhook para você. Para conexões com credencial manual e conector local, você mesmo cola o webhook no provedor:
Abra a página de detalhe do repositório e vá até a seção Webhook de VCS. Copie a URL do webhook de entrada e a chave de assinatura.
Nas configurações do seu provedor de VCS, crie um webhook. Cole a URL no campo de payload ou target URL e a chave no campo de secret.
Assine os eventos de pull request ou merge request para que o provedor notifique a Acrity quando um PR/MR for aberto ou atualizado.
Volte à seção Webhook de VCS e revalide. A Acrity confirma que consegue receber eventos antes de o repositório ficar Pronto.
```mermaid theme={null}
sequenceDiagram
participant Dev as Desenvolvedor
participant VCS as Provedor de VCS
participant Acrity as Webhook de entrada da Acrity
participant Review as Execução de revisão
Dev->>VCS: Abrir ou atualizar PR/MR
VCS->>Acrity: Enviar evento de PR/MR para o webhook de entrada
Acrity->>Acrity: Verificar chave de assinatura e regras de branch
Acrity->>Review: Iniciar execução de revisão
Review-->>Dev: Publicar comentários de revisão no PR/MR
```
## Bootstrap de arquitetura
A aba Bootstrap ajuda a preparar uma documentação de arquitetura para o repositório quando o fluxo estiver disponível.
Use para:
* verificar se o repositório já tem documentação de arquitetura;
* iniciar geração assistida;
* revisar o material proposto;
* escolher branch alvo quando aplicável;
* concluir o fluxo com ou sem commit, conforme opção exibida;
* repetir ou reiniciar quando a tela indicar que é permitido.
Revise o conteúdo gerado antes de publicar no repositório. A responsabilidade por aceitar e versionar a documentação é da organização.
## Security scans
Quando habilitado, o repositório pode exibir informações de varreduras de segurança e dependências. Use a tela para acompanhar último scan, próxima execução e ações disponíveis.
Detalhes de dados e segurança ficam em `Segurança > Tratamento de dados`.
## Problemas comuns
| Sintoma | O que verificar |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Repositório não fica pronto | Confira credencial, aplicativo conectado, conector, permissões e webhook. |
| Reviews não disparam | Veja se o repositório está pausado, se o webhook está válido e se as regras de branch estão ignorando o evento. Acompanhe o estado da revisão no painel de Ops; use o Audit Trail apenas para detalhes técnicos de eventos e diagnóstico. |
| Comentários aparecem no idioma errado | Confira idioma do repositório e idioma do workspace. |
| Tarefa de PM não é encontrada | Revise fontes de extração e campos configurados na aba PM. |
| Muitos PRs irrelevantes são revisados | Ajuste regras de branch, draft review e política de autores no workspace. |