guardia-ai/gitlab-componentScanner di conformità all'EU AI Act per pipeline GitLab CI/CD — rileva librerie AI/ML e pubblica la classificazione del rischio come commenti MR.
Per facilitare l'inizio con GitLab, ecco un elenco di passaggi consigliati.
Sei già un professionista? Modifica semplicemente questo README.md e personalizzalo. Vuoi renderlo facile? Usa il modello in fondo!
cd existing_repo
git remote add origin https://gitlab.com/guardia-ai/gitlab-component.git
git branch -M main
git push -uf origin main
Utilizza l'integrazione continua integrata in GitLab.
Quando sei pronto per rendere questo README tuo, modifica questo file e usa il comodo modello qui sotto (o sentiti libero di strutturarlo come preferisci - questo è solo un punto di partenza!). Grazie a makeareadme.com per questo modello.
Ogni progetto è diverso, quindi considera quali di queste sezioni si applicano al tuo. Le sezioni usate nel modello sono suggerimenti per la maggior parte dei progetti open source. Tieni anche presente che mentre un README può essere troppo lungo e dettagliato, troppo lungo è meglio che troppo corto. Se pensi che il tuo README sia troppo lungo, considera l'utilizzo di un'altra forma di documentazione piuttosto che tagliare informazioni.
Scegli un nome autoesplicativo per il tuo progetto.
Fai sapere alle persone cosa può fare specificamente il tuo progetto. Fornisci contesto e aggiungi un link a eventuali riferimenti che i visitatori potrebbero non conoscere. Qui può anche essere aggiunta un elenco di funzionalità o una sottosezione di background. Se ci sono alternative al tuo progetto, questo è un buon posto per elencare i fattori differenzianti.
In alcuni README, potresti vedere piccole immagini che trasmettono metadati, come se tutti i test stanno passando per il progetto. Puoi usare Shields per aggiungerne al tuo README. Molti servizi hanno anche istruzioni per aggiungere un badge.
A seconda di cosa stai creando, può essere una buona idea includere screenshot o persino un video (vedrai spesso GIF anziché video reali). Strumenti come ttygif possono aiutare, ma dai un'occhiata ad Asciinema per un metodo più sofisticato.
All'interno di un particolare ecosistema, potrebbe esserci un modo comune di installare le cose, come usando Yarn, NuGet o Homebrew. Tuttavia, considera la possibilità che chi legge il tuo README sia un principiante e desideri maggiori indicazioni. Elencare passaggi specifici aiuta a rimuovere ambiguità e porta le persone a usare il tuo progetto il più rapidamente possibile. Se funziona solo in un contesto specifico come una particolare versione del linguaggio di programmazione o sistema operativo o ha dipendenze che devono essere installate manualmente, aggiungi anche una sottosezione Requisiti.
Usa esempi liberamente e mostra l'output previsto se puoi. È utile avere inline il più piccolo esempio di utilizzo che puoi dimostrare, fornendo collegamenti a esempi più sofisticati se sono troppo lunghi da includere ragionevolmente nel README.
Dì alle persone dove possono andare per ricevere aiuto. Può essere qualsiasi combinazione di un issue tracker, una chat room, un indirizzo email, ecc.
Se hai idee per versioni future, è una buona idea elencarle nel README.
Dichiara se sei aperto a contributi e quali sono i tuoi requisiti per accettarli.
Per le persone che vogliono apportare modifiche al tuo progetto, è utile avere della documentazione su come iniziare. Forse c'è uno script che dovrebbero eseguire o alcune variabili d'ambiente che devono impostare. Rendi espliciti questi passaggi. Queste istruzioni potrebbero essere utili anche al tuo futuro te stesso.
Puoi anche documentare comandi per lintare il codice o eseguire test. Questi passaggi aiutano a garantire un'alta qualità del codice e riducono la probabilità che le modifiche rompano involontariamente qualcosa. Avere istruzioni per eseguire i test è particolarmente utile se richiede configurazioni esterne, come l'avvio di un server Selenium per test in un browser.
Mostra il tuo apprezzamento a coloro che hanno contribuito al progetto.
Per progetti open source, indica come è concesso in licenza.
Se hai esaurito energia o tempo per il tuo progetto, inserisci una nota all'inizio del README dicendo che lo sviluppo è rallentato o si è fermato completamente. Qualcuno potrebbe scegliere di fare un fork del tuo progetto o offrirsi volontario come manutentore o proprietario, permettendo al tuo progetto di continuare. Puoi anche fare una richiesta esplicita di manutentori.
Oltre a rilevare quali librerie AI utilizzi, lo scanner legge il tuo codice sorgente e segnala obblighi specifici su righe specifiche:
| Regola | Cosa cerca |
|---|---|
GA-ART50-001 | Un endpoint rivolto all'utente che raggiunge un modello, senza alcuna informazione nel repository che le risposte sono generate dall'IA |
GA-ART12-001 | Un modello invocato senza chiamate di logging, audit o tracing nell'ambito |
I risultati appaiono in tre modi: come commento nella merge request, come marcatori nel diff della merge request tramite il report Code Quality e — con una chiave API — come record nella dashboard Guardia che tiene traccia di ciò che hai risolto e di ciò che hai introdotto, commit per 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'
I risultati si risolvono da soli. Correggi il codice — la nostra patch o la tua — e la prossima scansione semplicemente smetterà di segnalarlo. Niente da cliccare.
Per accettarne uno invece, dichiaralo nel codice:
# guardia: ignore GA-ART50-001 — notice is rendered by the chat UI shell
Questo non fa mai fallire una build, e arriva nella tua dashboard come accettazione del rischio documentata con l'autore ricavato da git blame, che è ciò che un revisore vuole vedere.
Un repository di cinque anni avrà risultati che nessuno attualmente nel team ha causato. Congelali una volta, e solo il nuovo lavoro deve essere pulito:
guardia-scan . --write-baseline .guardia/baseline.json
Fai il commit di quel file. I risultati con baseline rimangono visibili nel report e nella tua dashboard — semplicemente non fanno mai fallire il controllo. Qualsiasi cosa introdotta successivamente lo fa.
Ogni esecuzione può scrivere un record a prova di manomissione — cosa è stato trovato, su quale commit, sotto quale versione del pacchetto di regole, e quanto esame legale aveva ogni regola al momento:
- uses: GharbiiAhmed/guardia-ai-action@v1
with:
evidence-file: guardia-evidence.json
evidence-signing-key: ${{ secrets.GUARDIA_EVIDENCE_KEY }} # optional
I record si concatenano tramite hash, quindi alterarne uno passato rompe ogni record successivo. Senza una chiave di firma che prova la coerenza interna, non l'autenticità — il record lo dice da sé piuttosto che lasciartelo supporre.
I risultati descrivono cosa fa il tuo codice e citano l'obbligo. Non affermano che tu sia in violazione — se un obbligo si applica dipende dallo scopo del tuo sistema e dal contesto di distribuzione, che nessuna scansione di codice può determinare. Le regole citano il Regolamento (UE) 2024/1689 testualmente in modo che tu possa verificare il ragionamento da solo.
Il rilevamento viene eseguito interamente offline. Il tuo codice sorgente non lascia mai il runner.