guardia-ai/gitlab-componentEU AI Act compliance scanner für GitLab CI/CD-Pipelines – erkennt KI/ML-Bibliotheken und veröffentlicht Risikoklassifizierung als MR-Kommentare.
Um den Einstieg in GitLab zu erleichtern, finden Sie hier eine Liste empfohlener nächster Schritte.
Bereits ein Profi? Bearbeiten Sie einfach diese README.md und machen Sie sie zu Ihrer eigenen. Sie möchten es einfach haben? Nutzen Sie die Vorlage am Ende!
cd existing_repo
git remote add origin https://gitlab.com/guardia-ai/gitlab-component.git
git branch -M main
git push -uf origin main
Nutzen Sie die integrierte kontinuierliche Integration in GitLab.
Wenn Sie bereit sind, diese README zu Ihrer eigenen zu machen, bearbeiten Sie einfach diese Datei und verwenden Sie die praktische Vorlage unten (oder strukturieren Sie sie nach Belieben – dies ist nur ein Ausgangspunkt!). Danke an makeareadme.com für diese Vorlage.
Jedes Projekt ist anders, daher überlegen Sie, welche dieser Abschnitte auf Ihr Projekt zutreffen. Die in der Vorlage verwendeten Abschnitte sind Vorschläge für die meisten Open-Source-Projekte. Beachten Sie auch, dass eine README zwar zu lang und detailliert sein kann, aber zu lang ist besser als zu kurz. Wenn Sie denken, dass Ihre README zu lang ist, ziehen Sie in Betracht, eine andere Form der Dokumentation zu verwenden, anstatt Informationen herauszuschneiden.
Wählen Sie einen selbsterklärenden Namen für Ihr Projekt.
Lassen Sie die Leute wissen, was Ihr Projekt konkret kann. Geben Sie Kontext und fügen Sie einen Link zu Referenzen hinzu, mit denen Besucher möglicherweise nicht vertraut sind. Eine Liste von Funktionen oder ein Unterabschnitt zum Hintergrund können hier ebenfalls hinzugefügt werden. Falls es Alternativen zu Ihrem Projekt gibt, ist dies ein guter Ort, um Unterscheidungsmerkmale aufzulisten.
In manchen READMEs sehen Sie kleine Bilder, die Metadaten vermitteln, z. B. ob alle Tests für das Projekt bestanden werden. Sie können Shields verwenden, um solche in Ihre README aufzunehmen. Viele Dienste bieten auch Anleitungen zum Hinzufügen eines Badges.
Je nachdem, was Sie erstellen, kann es sinnvoll sein, Screenshots oder sogar ein Video einzufügen (häufig sieht man GIFs statt Videos). Tools wie ttygif können helfen, aber schauen Sie sich Asciinema für eine anspruchsvollere Methode an.
Innerhalb eines bestimmten Ökosystems gibt es möglicherweise eine gängige Installationsmethode, z. B. mit Yarn, NuGet oder Homebrew. Bedenken Sie jedoch, dass die Person, die Ihre README liest, ein Anfänger sein könnte und mehr Anleitung wünscht. Die Auflistung konkreter Schritte hilft, Unklarheiten zu beseitigen und ermöglicht es anderen, Ihr Projekt so schnell wie möglich zu nutzen. Wenn es nur in einem bestimmten Kontext läuft (z. B. einer bestimmten Programmiersprachenversion oder einem Betriebssystem) oder Abhängigkeiten hat, die manuell installiert werden müssen, fügen Sie auch einen Unterabschnitt „Anforderungen“ hinzu.
Verwenden Sie großzügig Beispiele und zeigen Sie nach Möglichkeit die erwartete Ausgabe. Es ist hilfreich, das kleinste Anwendungsbeispiel, das Sie demonstrieren können, direkt einzufügen, während Sie Links zu komplexeren Beispielen bereitstellen, wenn diese zu lang sind, um sie in die README aufzunehmen.
Teilen Sie den Leuten mit, wo sie Hilfe bekommen können. Das kann jede Kombination aus Issue-Tracker, Chatraum, E-Mail-Adresse usw. sein.
Wenn Sie Ideen für zukünftige Versionen haben, ist es eine gute Idee, diese in der README aufzulisten.
Geben Sie an, ob Sie offen für Beiträge sind und welche Anforderungen Sie an deren Annahme stellen.
Für Personen, die Änderungen an Ihrem Projekt vornehmen möchten, ist es hilfreich, eine Dokumentation zum Einstieg zu haben. Vielleicht gibt es ein Skript, das sie ausführen sollen, oder Umgebungsvariablen, die sie setzen müssen. Machen Sie diese Schritte explizit. Diese Anweisungen können auch für Ihr zukünftiges Ich nützlich sein.
Sie können auch Befehle zum Linten des Codes oder zum Ausführen von Tests dokumentieren. Diese Schritte tragen dazu bei, eine hohe Codequalität sicherzustellen und die Wahrscheinlichkeit zu verringern, dass Änderungen versehentlich etwas kaputt machen. Anweisungen zum Ausführen von Tests sind besonders hilfreich, wenn eine externe Einrichtung erforderlich ist, z. B. das Starten eines Selenium-Servers zum Testen in einem Browser.
Zeigen Sie Ihre Wertschätzung für diejenigen, die zum Projekt beigetragen haben.
Geben Sie bei Open-Source-Projekten an, wie es lizenziert ist.
Wenn Ihnen die Energie oder Zeit für Ihr Projekt ausgegangen ist, fügen Sie oben in der README einen Hinweis ein, dass die Entwicklung verlangsamt oder vollständig eingestellt wurde. Jemand könnte sich entscheiden, Ihr Projekt zu forken oder sich freiwillig als Betreuer oder Eigentümer zu melden, damit Ihr Projekt weiterläuft. Sie können auch explizit nach Betreuern suchen.
Über die Erkennung welcher KI-Bibliotheken Sie verwenden hinaus, liest der Scanner Ihren Quellcode und meldet spezifische Pflichten an bestimmten Zeilen:
| Regel | Wonach es sucht |
|---|---|
GA-ART50-001 | Ein benutzerseitiger Endpunkt, der auf ein Modell zugreift, ohne dass irgendwo im Repository offengelegt wird, dass Antworten KI-generiert sind |
GA-ART12-001 | Ein Modell, das ohne Protokollierung, Prüfungs- oder Ablaufverfolgungsaufruf im Gültigkeitsbereich aufgerufen wird |
Ergebnisse erscheinen auf drei Arten: als Kommentar im Merge Request, als Markierungen im Merge Request-Diff über den Code-Qualitätsbericht und – mit einem API-Schlüssel – als Eintrag in Ihrem Guardia-Dashboard, der nachverfolgt, was Sie behoben und was Sie eingeführt haben, Commit für 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'
Ergebnisse lösen sich von selbst. Beheben Sie den Code – unseren Patch oder Ihren eigenen – und der nächste Scan meldet ihn einfach nicht mehr. Nichts zum Klicken.
Um stattdessen eines zu akzeptieren, geben Sie dies im Code an:
# guardia: ignore GA-ART50-001 — notice is rendered by the chat UI shell
Das führt niemals zu einem Build-Fehler und wird in Ihrem Dashboard als dokumentierte Risikoakzeptanz mit dem Autor aus git blame angezeigt, was ein Prüfer sehen möchte.
Ein fünf Jahre altes Repository wird Ergebnisse enthalten, die niemand im aktuellen Team verursacht hat. Frieren Sie sie einmal ein, und nur neue Arbeiten müssen sauber sein:
guardia-scan . --write-baseline .guardia/baseline.json
Committen Sie diese Datei. Baseline-Ergebnisse bleiben im Bericht und in Ihrem Dashboard sichtbar – sie lassen nur nie den Check fehlschlagen. Alles, was danach eingeführt wird, schon.
Jeder Durchlauf kann einen manipulationssicheren Datensatz schreiben – was gefunden wurde, bei welchem Commit, unter welcher Version des Regelpakets und wie viel rechtliche Prüfung jede Regel zu diesem Zeitpunkt hatte:
- uses: GharbiiAhmed/guardia-ai-action@v1
with:
evidence-file: guardia-evidence.json
evidence-signing-key: ${{ secrets.GUARDIA_EVIDENCE_KEY }} # optional
Datensätze sind per Hash verkettet, sodass die Änderung eines früheren jeden nachfolgenden Datensatz ungültig macht. Ohne einen Signaturschlüssel, der interne Konsistenz beweist, nicht Authentizität – der Datensatz sagt es selbst, anstatt dass Sie es annehmen müssen.
Ergebnisse geben an, was Ihr Code tut, und zitieren die Pflicht. Sie behaupten nicht, dass Sie gegen etwas verstoßen – ob eine Pflicht gilt, hängt vom Zweck Ihres Systems und dem Bereitstellungskontext ab, den kein Code-Scan bestimmen kann. Die Regeln zitieren die Verordnung (EU) 2024/1689 wörtlich, damit Sie die Begründung selbst überprüfen können.
Die Erkennung läuft vollständig offline. Ihr Quellcode verlässt den Runner nie.