guardia-ai/gitlab-componentScanner de conformidade com o EU AI Act para pipelines CI/CD do GitLab — detecta bibliotecas de IA/ML e publica classificação de risco como comentários MR.
Para facilitar o início com o GitLab, aqui está uma lista de próximos passos recomendados.
Já é um profissional? Basta editar este README.md e torná-lo seu. Quer facilitar? Use o modelo no final!
cd existing_repo
git remote add origin https://gitlab.com/guardia-ai/gitlab-component.git
git branch -M main
git push -uf origin main
Use a integração contínua integrada no GitLab.
Quando estiver pronto para personalizar este README, basta editar este arquivo e usar o modelo prático abaixo (ou sinta-se à vontade para estruturá-lo como quiser - este é apenas um ponto de partida!). Agradecimentos a makeareadme.com por este modelo.
Cada projeto é diferente, então considere quais destas seções se aplicam ao seu. As seções usadas no modelo são sugestões para a maioria dos projetos de código aberto. Lembre-se também que, embora um README possa ser muito longo e detalhado, muito longo é melhor que muito curto. Se você acha que seu README é muito longo, considere utilizar outra forma de documentação em vez de cortar informações.
Escolha um nome autoexplicativo para o seu projeto.
Deixe as pessoas saberem especificamente o que seu projeto pode fazer. Forneça contexto e adicione um link para qualquer referência que os visitantes possam não conhecer. Uma lista de Recursos ou uma subseção de Contexto também pode ser adicionada aqui. Se houver alternativas ao seu projeto, este é um bom lugar para listar fatores diferenciadores.
Em alguns READMEs, você pode ver pequenas imagens que transmitem metadados, como se todos os testes estão passando para o projeto. Você pode usar Shields para adicionar alguns ao seu README. Muitos serviços também têm instruções para adicionar um distintivo.
Dependendo do que você está fazendo, pode ser uma boa ideia incluir capturas de tela ou até mesmo um vídeo (você verá frequentemente GIFs em vez de vídeos reais). Ferramentas como ttygif podem ajudar, mas confira Asciinema para um método mais sofisticado.
Dentro de um ecossistema específico, pode haver uma maneira comum de instalar coisas, como usando Yarn, NuGet ou Homebrew. No entanto, considere a possibilidade de que quem está lendo seu README seja um novato e gostaria de mais orientação. Listar etapas específicas ajuda a remover ambiguidade e faz com que as pessoas usem seu projeto o mais rápido possível. Se ele for executado apenas em um contexto específico, como uma versão específica de linguagem de programação ou sistema operacional, ou tiver dependências que precisam ser instaladas manualmente, adicione também uma subseção de Requisitos.
Use exemplos liberalmente e mostre a saída esperada se puder. É útil ter em linha o menor exemplo de uso que você pode demonstrar, fornecendo links para exemplos mais sofisticados se eles forem muito longos para incluir razoavelmente no README.
Diga às pessoas onde elas podem obter ajuda. Pode ser qualquer combinação de um rastreador de issues, uma sala de chat, um endereço de e-mail, etc.
Se você tem ideias para versões futuras, é uma boa ideia listá-las no README.
Informe se você está aberto a contribuições e quais são seus requisitos para aceitá-las.
Para pessoas que desejam fazer alterações no seu projeto, é útil ter alguma documentação sobre como começar. Talvez haja um script que elas devem executar ou algumas variáveis de ambiente que precisam definir. Torne essas etapas explícitas. Essas instruções também podem ser úteis para você no futuro.
Você também pode documentar comandos para lint do código ou executar testes. Essas etapas ajudam a garantir alta qualidade do código e reduzem a probabilidade de que as alterações quebrem algo inadvertidamente. Ter instruções para executar testes é especialmente útil se exigir configuração externa, como iniciar um servidor Selenium para testar em um navegador.
Mostre seu apreço àqueles que contribuíram para o projeto.
Para projetos de código aberto, informe como é licenciado.
Se você ficou sem energia ou tempo para seu projeto, coloque uma nota no topo do README dizendo que o desenvolvimento desacelerou ou parou completamente. Alguém pode optar por bifurcar seu projeto ou se voluntariar para atuar como mantenedor ou proprietário, permitindo que seu projeto continue. Você também pode fazer uma solicitação explícita por mantenedores.
Além de detectar quais bibliotecas de IA você usa, o scanner lê seu código-fonte e relata obrigações específicas em linhas específicas:
| Regra | O que procura |
|---|---|
GA-ART50-001 | Um endpoint voltado para o usuário que acessa um modelo, sem nenhuma divulgação em qualquer lugar do repositório de que as respostas são geradas por IA |
GA-ART12-001 | Um modelo invocado sem nenhuma chamada de registro, auditoria ou rastreamento no escopo |
As descobertas aparecem de três maneiras: como um comentário na solicitação de merge, como marcadores no diff da solicitação de merge por meio do relatório de Qualidade de Código e — com uma chave de API — como um registro no seu painel Guardia que rastreia o que você corrigiu e o que introduziu, commit por commit.
include:
- component: gitlab.com/guardia-ai/gitlab-component/scan@main
inputs:
guardia_api_key: $GUARDIA_API_KEY # optional — keeps the record
code_analysis: 'true'
fail_on_findings: 'none'
As descobertas se resolvem sozinhas. Corrija o código — nosso patch ou o seu — e a próxima verificação simplesmente para de relatar. Nada para clicar.
Para aceitar uma em vez disso, diga isso no código:
# guardia: ignore GA-ART50-001 — notice is rendered by the chat UI shell
Isso nunca falha em uma construção, e chega ao seu painel como uma aceitação de risco documentada com o autor do git blame, que é o que um auditor quer ver.
Um repositório de cinco anos terá descobertas que ninguém atualmente na equipe causou. Congele-as uma vez, e apenas o trabalho novo precisa estar limpo:
guardia-scan . --write-baseline .guardia/baseline.json
Faça commit desse arquivo. As descobertas na linha de base permanecem visíveis no relatório e no seu painel — elas simplesmente nunca falham na verificação. Qualquer coisa introduzida depois falha.
Cada execução pode escrever um registro à prova de adulteração — o que foi encontrado, em qual commit, sob qual versão do pacote de regras e quanta revisão legal cada regra teve no momento:
- uses: GharbiiAhmed/guardia-ai-action@v1
with:
evidence-file: guardia-evidence.json
evidence-signing-key: ${{ secrets.GUARDIA_EVIDENCE_KEY }} # optional
Os registros são encadeados por hash, então alterar um passado quebra todos os registros posteriores. Sem uma chave de assinatura que prova consistência interna, não autenticidade — o próprio registro diz isso em vez de deixar você presumir.
As descobertas declaram o que seu código faz e citam a obrigação. Elas não afirmam que você está em violação — se uma obrigação se aplica depende do propósito e do contexto de implantação do seu sistema, que nenhuma verificação de código pode determinar. As regras citam o Regulamento (UE) 2024/1689 na íntegra para que você possa verificar o raciocínio por si mesmo.
A detecção é executada inteiramente offline. Seu código-fonte nunca sai do runner.