GitLab CI

GitLab has no official CodeCharter integration as a component, but a few lines of YAML are enough to run the CLI cleanly in the pipeline.

Minimal setup

.gitlab-ci.yml:

codecharter:
  image: mcr.microsoft.com/dotnet/sdk:9.0
  stage: test
  before_script:
    - curl -sSL -H "Authorization: Bearer $CODECHARTER_API_KEY"
        -o codecharter.tar.gz
        https://codecharter.tools/api/v1/cli/linux-x64/latest
    - mkdir -p /opt/codecharter && tar -xzf codecharter.tar.gz -C /opt/codecharter
    - chmod +x /opt/codecharter/codecharter
    - export PATH="/opt/codecharter:$PATH"
  script:
    - codecharter analyze . --fail-on error --output sarif --output-file codecharter.sarif
  artifacts:
    when: always
    paths:
      - codecharter.sarif
    reports:
      sast: codecharter.sarif

Getting an API key

1. Generate a key in the portal under API Keys.
2. In GitLab, go to Settings → CI/CD → Variables and store it as CODECHARTER_API_KEY with "Protected" and "Masked" enabled.

SARIF for GitLab SAST

SARIF is GitLab's native format for static analysis. When artifacts.reports.sast points to the SARIF file, findings appear:

• On the MR overview as annotations
• In "Security & Compliance → Vulnerability Report" as issues
• In the "Code Quality" tab

Caching

Persist the CodeCharter cache between pipelines:

codecharter:
  # ... as above ...
  cache:
    key: codecharter-$CI_COMMIT_REF_SLUG
    paths:
      - .cache/codecharter/
  variables:
    CODECHARTER_CACHE_DIR: $CI_PROJECT_DIR/.cache/codecharter

On a medium-sized solution this brings a warm run down from 30 seconds to 5–10 seconds.

Version pinning

Instead of /latest/, pull a specific CLI version:

- curl -sSL -H "Authorization: Bearer $CODECHARTER_API_KEY"
    -o codecharter.tar.gz
    https://codecharter.tools/api/v1/cli/linux-x64/1.4.0

Recommendation: always pin in CI, see Versioning.

Self-hosted GitLab runners

A self-hosted runner needs one-time access to codecharter.tools and harbor.bochmann-software.com (if you pull Docker images). No other changes required.

In air-gapped networks: mirror the CLI binary to the runner and use a local path instead of a curl download.

Merge request reports

Optionally use the code_quality output variant (in GitLab's own format) for the "Code Quality" section on MRs:

script:
  - codecharter analyze . --fail-on error --output json --output-file codecharter.json
  - # convert to GitLab Code Quality format
artifacts:
  reports:
    codequality: codecharter.json

You can build the converter quickly with jq.

Pipeline variables

Useful variables available in the job:

Variable	Usage
$CI_PROJECT_DIR	Repo root
$CI_COMMIT_REF_SLUG	Branch name for caching
$CI_MERGE_REQUEST_IID	MR number when present
$CODECHARTER_API_KEY	Your secret