CI CD Integration

CI/CD Integration

CoreTrace Stack Analyzer integrates into CI/CD pipelines via three methods: the reusable GitHub Action module, the CI adapter script, and Docker images.

---

Method 1: GitHub Action Module (Recommended)

The simplest way to integrate. Other repositories consume the analyzer directly with uses:.

name: Stack Analysis

on:
  pull_request:
  workflow_dispatch:

jobs:
  analyze:
    runs-on: ubuntu-24.04
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - name: Generate compile_commands.json
        run: cmake -S . -B build -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

      - name: Run CoreTrace Stack Analyzer
        uses: CoreTrace/coretrace-stack-analyzer@v0
        with:
          compile-commands: build/compile_commands.json
          analysis-profile: fast
          resource-model: default
          resource-cache-memory-only: "true"
          fail-on: error
          sarif-file: artifacts/coretrace-stack-analysis.sarif
          json-file: artifacts/coretrace-stack-analysis.json
          upload-sarif: "true"

Action Inputs

Input	Default	Description
sources	auto	Source files (space-separated). Auto-discovered from compdb if omitted.
compile-commands	auto	Path to compile_commands.json. Auto-detected from common locations.
fail-on	error	CI gate: none, error, or warning.
analysis-profile	fast	fast or full.
resource-model	default	Resource model path. default uses the bundled model.
resource-cache-memory-only	true	Memory-only cross-TU cache.
sarif-file	coretrace-stack-analysis.sarif	SARIF output path.
json-file	coretrace-stack-analysis.json	JSON output path.
upload-sarif	true	Auto-upload SARIF to GitHub Code Scanning.
warnings-only	false	Emit only warnings/errors.
stack-limit	-	Override stack limit (e.g., 1MiB).
extra-args	-	Extra analyzer arguments (space-separated).
inputs-from-git-fallback	true	Fall back to git-tracked sources if no compdb found.
llvm-version	20	LLVM version to install.

Action Outputs

Output	Description
sarif-file	Path to the generated SARIF report
json-file	Path to the generated JSON report
errors	Number of errors found
warnings	Number of warnings found

Compile Commands Auto-Detection

If compile-commands is not provided, the action searches:

1. build/compile_commands.json
2. compile_commands.json
3. .coretrace/build-linux/compile_commands.json

If none found and inputs-from-git-fallback is true, it analyzes git-tracked source files directly.

---

Method 2: CI Adapter Script

The scripts/ci/run_code_analysis.py script wraps the analyzer binary with CI gate logic and report export.

python3 scripts/ci/run_code_analysis.py \
  --analyzer ./build/stack_usage_analyzer \
  --compdb ./build/compile_commands.json \
  --fail-on error \
  --json-out artifacts/stack-usage.json \
  --sarif-out artifacts/stack-usage.sarif \
  --print-diagnostics warning

CI Adapter Options

Option	Description
--analyzer <path>	Path to the analyzer binary
--compdb <path>	compile_commands.json (file or directory)
--fail-on none|error|warning	CI gate policy
--json-out <path>	JSON output file
--sarif-out <path>	SARIF output file
--analyzer-arg <arg>	Extra analyzer argument (repeatable)
--base-dir <path>	Base directory for relative SARIF paths
--inputs-from-git	Discover inputs from git-tracked files
--repo-root <path>	Repository root for git discovery
--exclude <pattern>	Exclude pattern (repeatable)
--print-diagnostics none|error|warning|info|all	Print diagnostics to stdout

Architecture

                CI Workflow
                    |
                    v
        run_code_analysis.py (CI adapter)
        - CI gate policy (fail-on)
        - Report export (JSON + SARIF)
        - Input discovery
                    |
                    v
          stack_usage_analyzer (analysis engine)
          - CI-agnostic
          - Reusable everywhere

---

Method 3: Docker Images

Runtime Image (Dockerfile)

For full-repo analysis with sensible defaults:

docker build -t coretrace-stack-analyzer .
docker run --rm -v "$PWD:/workspace" coretrace-stack-analyzer

Default behavior:

• Auto-detects compile_commands.json at /workspace/build/compile_commands.json
• Uses --analysis-profile=fast, --compdb-fast
• Enables --resource-summary-cache-memory-only
• Loads bundled resource model

Override defaults:

docker run --rm -v "$PWD:/workspace" coretrace-stack-analyzer \
  --analysis-profile=full --warnings-only

Bypass defaults entirely:

docker run --rm -v "$PWD:/workspace" coretrace-stack-analyzer --raw --help

CI Gate Image (Dockerfile.ci)

Entrypoint is run_code_analysis.py:

docker build -f Dockerfile.ci \
  --build-arg VERSION=0.1.0 \
  --build-arg VCS_REF="$(git rev-parse --short HEAD)" \
  -t ghcr.io/<org>/coretrace-stack-analyzer-ci:0.1.0 .

docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "$PWD:/workspace" -w /workspace \
  ghcr.io/<org>/coretrace-stack-analyzer-ci:0.1.0 \
  --inputs-from-git --repo-root /workspace \
  --compdb /workspace/build/compile_commands.json \
  --analyzer-arg=--analysis-profile=fast \
  --fail-on error \
  --json-out /workspace/artifacts/stack-usage.json \
  --sarif-out /workspace/artifacts/stack-usage.sarif

Extending Docker Images

If your project needs extra dependencies:

FROM ghcr.io/<org>/coretrace-stack-analyzer:0.1.0
RUN apt-get update && apt-get install -y --no-install-recommends \
    <project-dev-packages> \
    && rm -rf /var/lib/apt/lists/*

---

Generating compile_commands.json

Most C/C++ projects use CMake:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Important:

• Generate compile_commands.json in the same OS/toolchain as the analyzer run
• Reusing a macOS compile database in Linux CI often fails (Apple SDK paths, -arch flags)
• --compdb-fast improves portability by dropping heavy flags, but cannot replace missing headers

---

CI Gate Policy

The --fail-on option controls when the CI step fails:

Value	Behavior
none	Never fail (always exit 0)
error	Fail if any error-level diagnostics found
warning	Fail if any warnings or errors found

---

SARIF and GitHub Code Scanning

SARIF reports integrate with GitHub Code Scanning to show inline annotations on PRs:

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: artifacts/stack-usage.sarif
    category: coretrace-stack-analyzer

Use --base-dir to ensure SARIF URIs are relative to the repository root.

---

Workflow Examples

Ready-to-adapt workflow examples are available in the repository:

• docs/ci/github-actions-consumer.yml -- non-Docker consumer
• docs/ci/github-actions-module-consumer.yml -- uses: module consumer
• docs/ci/github-actions-docker-consumer.yml -- Docker consumer