GitHub Actions

Die offizielle Action bochmann-software/codeguard@v1 ist der schnellste Weg CodeGuard in einen GitHub-Workflow zu bauen. Sie kümmert sich um den CLI-Download, das Caching und das Veröffentlichen der Findings als PR-Annotations.

Minimal-Setup

.github/workflows/codeguard.yml:

name: CodeGuard

on:
  pull_request:
  push:
    branches: [main]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '9.0.x'
      - uses: bochmann-software/codeguard@v1
        with:
          solution: Acme.Web.sln
          api-key: ${{ secrets.CODEGUARD_API_KEY }}

Fertig. Findings tauchen automatisch im PR als Inline-Annotations auf.

API-Key beschaffen

1. Im Portal unter API Keys einen Key erzeugen.
2. Im GitHub-Repo unter Settings → Secrets → Actions als CODEGUARD_API_KEY hinterlegen.

Die Action liest den Key, authentifiziert gegen das Portal und pullt die zur Action-Version passende CLI.

Inputs

Outputs

Vollbild: SARIF + Code Scanning

Wenn ihr die Findings im Security-Tab eures GitHub-Repos sehen wollt:

- uses: bochmann-software/codeguard@v1
  id: codeguard
  with:
    solution: Acme.Web.sln
    api-key: ${{ secrets.CODEGUARD_API_KEY }}
    sarif-output: codeguard.sarif

- name: Upload SARIF
  if: always()
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: codeguard.sarif

if: always() damit das SARIF auch hochgeladen wird wenn die Action Findings hatte und Exit-Code 1 zurückgegeben hat.

Matrix-Builds

Wenn eure Solution auf mehreren OS gebaut wird, aber CodeGuard deterministisch ist, läuft die Analyse nur einmal:

jobs:
  build:
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v4
      - run: dotnet build

  codeguard:
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4
      - uses: bochmann-software/codeguard@v1
        with:
          api-key: ${{ secrets.CODEGUARD_API_KEY }}

Self-Hosted Runner

Funktioniert ohne Anpassungen, solange der Runner Internet-Zugriff auf codeguard.bochmann-software.com hat. Wenn nicht: das CLI-Binary einmal manuell auf den Runner kopieren und mit version: local arbeiten.

Versions-Pinning

Empfehlung: die Action auf eine konkrete Minor-Version pinnen und selten upgraden.

- uses: bochmann-software/codeguard@v1   # Major-pinning, kriegt v1.x.y Updates
- uses: bochmann-software/[email protected] # Minor-pinning, statisch
- uses: bochmann-software/codeguard@<sha> # SHA-pinning, am konservativsten

Wir folgen SemVer (siehe Versionierung) und brechen innerhalb einer Major-Version keine Verträge.

Caching

Die Action cached automatisch zwei Dinge:

1. Das CLI-Binary zwischen Workflow-Runs (per Action-Version-Hash).
2. Den CodeGuard-Analyse-Cache (per .codeguard/-Hash und Source-Files-Hash).

Auf einer mittleren Solution ist ein warmer Run typisch in 5-15 Sekunden durch.

Manuell deaktivieren wenn ihr unerklärliche Cache-Effekte debuggt:

- uses: bochmann-software/codeguard@v1
  with:
    cache: 'false'
    api-key: ${{ secrets.CODEGUARD_API_KEY }}

Wenn keine PR-Annotations auftauchen

GitHub zeigt Annotations nur auf Pull-Requests, nicht auf direkten push-Runs. Achte darauf dass der Workflow auf pull_request triggert.

Permissions

Standardmäßig braucht die Action contents: read. Wenn ihr SARIF hochladet zusätzlich security-events: write.

permissions:
  contents: read
  security-events: write