Bitbucket Pipelines

Bitbucket Pipelines führt CodeCharter als normalen Shell-Step im Docker-basierten Runner aus. Das Setup unten lädt die CLI herunter, analysiert die Solution und speichert den SARIF-Report als Pipeline-Artifact.

Liegt Ihr Repository auf GitHub und läuft nur der Build in Bitbucket Pipelines, können Sie aus dieser Pipeline zusätzlich einen gebrandeten CodeCharter-Check-Run und PR-Kommentar veröffentlichen, siehe Checks aus beliebigem CI veröffentlichen.

bitbucket-pipelines.yml:

image: mcr.microsoft.com/dotnet/sdk:9.0

pipelines:
  default:
    - step:
        name: CodeCharter
        caches:
          - codecharter
        script:
          - curl -sSL -H "Authorization: Bearer $CODECHARTER_API_KEY" \
              -o codecharter.tar.gz \
              https://codecharter.tools/api/v1/cli/linux-x64/1.0.12
          - mkdir -p /opt/codecharter && tar -xzf codecharter.tar.gz -C /opt/codecharter
          - chmod +x /opt/codecharter/codecharter
          - export PATH="/opt/codecharter:$PATH"
          - codecharter analyze MySolution.sln --fail-on error --output sarif:codecharter.sarif
        artifacts:
          - codecharter.sarif

definitions:
  caches:
    codecharter: .codecharter/cache

Ersetzen Sie MySolution.sln durch den Pfad zu Ihrer Solution- oder Projektdatei: analyze erwartet eine .sln-, .slnx- oder .csproj-Datei, kein Verzeichnis.

API-Key

In Bitbucket: Repository settings → Repository variables, Variable CODECHARTER_API_KEY anlegen, "Secured" aktivieren.

Die Variable erfüllt zwei Aufgaben: Der curl-Step lädt damit die CLI herunter, und der analyze-Step holt damit automatisch eine kurzlebige Lizenz, wenn keine im Cache liegt. Bitbucket stellt Repository-Variablen in jedem Step als Umgebungsvariablen bereit, weitere Konfiguration ist nicht nötig.

PR-Annotations via Bitbucket Reports API

Optional können Sie die Findings als Bitbucket Code Insights posten. CodeCharter hat dafür keinen direkten Konverter, aber das JSON-Format ist gut handzuhaben:

- codecharter analyze MySolution.sln --output json --output-file findings.json
- # Wandle findings.json in Code-Insights-API-Calls um
- python3 ./scripts/publish-to-bitbucket-insights.py findings.json

Pull-Request-Pipelines: nur geänderte Zeilen

In Pull-Request-Pipelines lassen sich sowohl die gemeldeten Findings als auch das --fail-on-Gate mit --git-ref auf die im PR geänderten Zeilen beschränken:

pipelines:
  pull-requests:
    '**':
      - step:
          name: CodeCharter (nur geänderte Zeilen)
          clone:
            depth: full
          script:
            # ... CLI-Download wie oben ...
            - git fetch origin $BITBUCKET_PR_DESTINATION_BRANCH
            - codecharter analyze MySolution.sln --fail-on error --git-ref "origin/$BITBUCKET_PR_DESTINATION_BRANCH..HEAD"

--git-ref führt intern git diff <range> --unified=0 aus, der Ziel-Branch muss also im Clone vorhanden sein (daher clone: depth: full und das git fetch).

Für Bestandscode gibt es außerdem Baseline-Unterstützung: --write-baseline zeichnet die aktuellen Findings einmalig auf, mit --baseline gelten Ausgabe und --fail-on danach nur noch für neue Findings.

Caching

CodeCharter hat keinen Cache für Analyseergebnisse, durch das Cachen von Analyse-Output lässt sich also nichts beschleunigen. Lohnend ist nur der Rule-Bundle-Cache: Wenn Ihr Projekt Portal-Regelprofile nutzt (eine .codecharter/codecharter.lock.json im Verzeichnis .codecharter/), landen heruntergeladene Bundles in .codecharter/cache. Der caches: codecharter-Block oben zusammen mit der Custom-Cache-Definition persistiert dieses Verzeichnis und erspart bei warmen Runs das erneute Herunterladen der Bundles.

Liegt Ihre Solution-Datei nicht im Repo-Root, passen Sie den Pfad in der Cache-Definition entsprechend an. Ohne Portal-Profile gibt es nichts zu cachen und Sie können die Cache-Blöcke weglassen.

Versions-Pinning

Wie immer empfohlen: konkrete CLI-Version pinnen, siehe Versionierung.

Jede Download-Antwort enthält einen X-CodeCharter-Sha256-Header. Vergleichen Sie ihn mit der Prüfsumme des heruntergeladenen Archivs, wenn Sie die Integrität des Downloads im Step verifizieren wollen.

Exit-Codes

Bitbucket markiert den Step bei jedem Exit-Code ungleich null als fehlgeschlagen. codecharter analyze verwendet diese Exit-Codes:

Schlägt die Pipeline plötzlich beim Download oder beim Analyze-Step mit HTTP 402 fehl, ist das Abo abgelaufen: Sowohl der CLI-Download als auch das Ausstellen der Lizenz liefern in diesem Fall 402.