GitHub Actions

The official action bochmann-software/codeguard@v1 is the fastest way to integrate CodeCharter into a GitHub workflow. It handles the CLI download, caching, and publishing findings as PR annotations.

Recommended: also install the CodeCharter GitHub App. The action then publishes a branded CodeCharter check run and PR comment through the app — no pull-requests: write permission and no GitHub token on the runner. Without the app the action still works and falls back to a workflow-token comment.

Minimal setup

.github/workflows/codecharter.yml:

name: CodeCharter

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.CODECHARTER_API_KEY }}

Done. Findings automatically appear as inline annotations on the PR.

Getting an API key

1. Generate a key in the portal under API Keys.
2. Store it as CODECHARTER_API_KEY in the GitHub repo under Settings → Secrets → Actions.

The action reads the key, authenticates against the portal, and pulls the CLI version matching the action version.

Inputs

Input	Default	Description
api-key		Required. API key from the portal.
solution	first .sln / .slnx	Which solution to analyze.
fail-on	error	Threshold for build failures (info, warn, error, never).
rules	.codecharter/	Path to the rule set.
version	latest	Which CLI version to use. Recommendation: pin it.
format	github	Output format (see Output Formats).
sarif-output		If set, SARIF is additionally written to this file.
cache	true	Persist the CodeCharter cache between CI runs.

Outputs

Output	Description
findings-total	Total number of findings
findings-error	Number of error findings
findings-warn	Number of warn findings
findings-info	Number of info findings
sarif-path	Path to the SARIF file, if generated

Full setup: SARIF + Code Scanning

If you want to see findings in the Security tab of your GitHub repo:

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

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

if: always() ensures SARIF is uploaded even when the action found findings and returned exit code 1.

Matrix builds

If your solution builds on multiple OSes but CodeCharter is deterministic, the analysis only needs to run once:

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

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

Self-hosted runners

Works without any changes as long as the runner has internet access to codecharter.tools. If not: copy the CLI binary to the runner manually and use version: local. Without portal access the CLI also cannot mint or renew its short-lived license from the API key, so place a full codecharter.license on the runner instead — see Offline or long-lived runners.

Version pinning

Recommendation: pin the action to a specific minor version and upgrade infrequently.

- uses: bochmann-software/codeguard@v1   # Major pinning, gets v1.x.y updates
- uses: bochmann-software/[email protected] # Minor pinning, static
- uses: bochmann-software/codeguard@<sha> # SHA pinning, most conservative

We follow SemVer (see Versioning) and do not break contracts within a major version.

Caching

The action automatically caches two things:

1. The CLI binary between workflow runs (keyed by action version hash).
2. The CodeCharter analysis cache (keyed by .codecharter/ hash and source files hash).

On a medium-sized solution a warm run typically completes in 5–15 seconds.

Disable manually when debugging unexplained cache effects:

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

If PR annotations don't appear

GitHub only shows annotations on pull requests, not on direct push runs. Make sure the workflow triggers on pull_request.

Permissions

By default the action needs contents: read. If you upload SARIF, add security-events: write.

permissions:
  contents: read
  security-events: write