CI-Integration

• Ein API-Schlüssel der Organisation, hinterlegt als geheime CI-Variable. In der Web-App angelegte Schlüssel tragen die Standard-Scopes; sie decken Hochladen, Analysen, das Lesen von Befunden und den Berichtsexport ab.
• Die ID eines bestehenden Projekts — legen Sie es einmalig in der Web-App an oder mit einem Schlüssel, der projects:write besitzt.
• Node.js 18 oder neuer auf dem Runner und das Paketverzeichnis der CLI in Ihrem Repository, da die CLI nicht in der öffentlichen npm-Registry veröffentlicht ist. Die Beispiele gehen davon aus, dass es als tools/erp-preflight-cli eingecheckt ist; es hat keine Abhängigkeiten, ein Installationsschritt entfällt daher.
• ERP_PREFLIGHT_API_URL und ERP_PREFLIGHT_API_KEY als Umgebungsvariablen des Jobs; login ist in CI nicht nötig.

--fail-on erwartet eine kommagetrennte Liste von Schweregraden: BLOCKER, CRITICAL, MAJOR, MEDIUM, MINOR, LOW, INFO (Groß- und Kleinschreibung spielen keine Rolle). Das Tor schlägt fehl, sobald mindestens ein Befund einen der aufgeführten Schweregrade hat. Die Liste ist kein Schwellenwert: --fail-on CRITICAL schlägt bei BLOCKER-Befunden nicht fehl. Nennen Sie daher jeden Schweregrad, der den Build brechen soll, etwa --fail-on BLOCKER,CRITICAL.

• Das Tor wird von analyze … --wait und von findings ausgewertet. Ohne --wait kehrt analyze direkt nach dem Einreihen zurück und wertet kein Tor aus.
• Endet ein Lauf mit FAILED oder CANCELLED, beendet sich die CLI mit Code 1 — mit oder ohne --fail-on. Ein PARTIAL-Lauf wird anhand der Befunde bewertet, die er erzeugt hat.
• Um einen anderswo gestarteten Lauf zu prüfen, verwenden Sie findings --analysis <analysisId> --fail-on BLOCKER,CRITICAL.

Exit-Codes: 0 Tor bestanden, 3 Tor verletzt, 1 Fehler (auch ein fehlgeschlagener Lauf oder ein Timeout von --wait), 2 Aufruf- oder Authentifizierungsproblem (auch ein fehlender Scope).

Hinterlegen Sie den Schlüssel als Repository-Secret ERP_PREFLIGHT_API_KEY und die Projekt-ID als Variable ERP_PREFLIGHT_PROJECT_ID:

name: sap-preflight
on:
  pull_request:
jobs:
  preflight:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - name: Clean-Core-Qualitätstor
        env:
          ERP_PREFLIGHT_API_URL: https://api.example.com
          ERP_PREFLIGHT_API_KEY: ${{ secrets.ERP_PREFLIGHT_API_KEY }}
          PROJECT_ID: ${{ vars.ERP_PREFLIGHT_PROJECT_ID }}
        run: |
          node tools/erp-preflight-cli/bin/erp-preflight.js analyze clean-core ./src \
            --project "$PROJECT_ID" --wait --timeout 900 \
            --fail-on BLOCKER,CRITICAL --json > preflight-result.json
      - name: Ergebnis aufbewahren
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: preflight-result
          path: preflight-result.json

Der Schritt lädt die passenden Dateien unter ./src in das Projekt hoch, führt Clean Core Object Guard aus und lässt den Job fehlschlagen, wenn ein BLOCKER- oder CRITICAL-Befund existiert. Mit --json wird das Ergebnis geschrieben, bevor das Tor ausgewertet wird; das Artefakt bleibt also auch bei einem fehlgeschlagenen Job erhalten.

Legen Sie ERP_PREFLIGHT_API_URL, ERP_PREFLIGHT_API_KEY (maskiert) und ERP_PREFLIGHT_PROJECT_ID als CI/CD-Variablen des Projekts an:

sap-preflight:
  image: node:20
  stage: test
  script:
    - node tools/erp-preflight-cli/bin/erp-preflight.js analyze clean-core ./src --project "$ERP_PREFLIGHT_PROJECT_ID" --wait --timeout 900 --fail-on BLOCKER,CRITICAL --json > preflight-result.json
  artifacts:
    when: always
    paths:
      - preflight-result.json

Der Job endet mit Exit-Code 3, wenn das Tor verletzt ist, und mit 1 oder 2 bei Fehlern; GitLab markiert die Pipeline in jedem dieser Fälle als fehlgeschlagen.

• Um Dateien zu prüfen, die bereits im Projekt liegen, führen Sie analyze <projectId> --engines <engine> --files <fileId,...> --wait --fail-on BLOCKER,CRITICAL aus, statt sie erneut hochzuladen.
• Für einen Bericht zur Pipeline entnehmen Sie analysisId der --json-Ausgabe und führen report export <projectId> <analysisId> --format PDF --out preflight.pdf aus.
• Geben Sie jeder Pipeline einen eigenen Schlüssel mit Ablaufdatum und widerrufen Sie ihn, wenn die Pipeline stillgelegt wird.
• Erhöhen Sie --timeout bei großen Uploads; ein Timeout von --wait endet mit Exit-Code 1.