axon-ci Overview

Axon CI/CD Templates

This repository contains shared GitLab CI/CD templates for the Axon language ecosystem. By centralizing these pipelines, we keep our repositories DRY and ensure uniform quality and security checks.

Available Templates

`templates/c-compiler.yml`

Core compiler and C-based system components (libaxon_pal). Builds QBE, compiles debug/release modes, runs AddressSanitizer, and uploads release binaries to GitLab Package Registry on tag.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/c-compiler.yml'

`templates/c-security.yml`

SAST, cppcheck, and strict compiler warning analysis for C components. security:cppcheck, security:warnings, security:hardened-build. All jobs are allow_failure: true.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/c-security.yml'

`templates/axon-library.yml`

Pure Axon library repos (axon-std, axon-ui, axon-web). Type-checks all .axs files, runs E2E tests with .expected files, runs .test marker tests, and publishes source tarball to Package Registry on SemVer tags.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/axon-library.yml'

`templates/pages.yml`

Generic GitLab Pages deployment for Markdown and static sites.

`templates/axon-examples.yml`

Example/showcase repos (axon-examples). Compiles all .axs files, runs golden file tests, verifies formatting idempotency, and publishes binary size + compile time metrics as GitLab metrics reports. QBE pinned for supply-chain safety.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/axon-examples.yml'

variables:
  SKIP_LIST: "wc math_demo linked_list http_server echo_server routing_server gui_calculator rest_api async_pipeline"

`templates/axon-std.yml`

Axon standard library (axon-std). Type-checking, golden-file E2E, integration tests, conditional async tests (auto-skips if modules absent), conditional raylib FFI tests (auto-skips if raylib absent), and per-module metrics. Same QBE pin as axon-examples.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/axon-std.yml'

variables:
  SKIP_LIST: ""   # space-separated module names to skip in metrics

`templates/axon-pkg-tool.yml`

Pure Axon tool repos (axon-pkg’s axpm). Downloads axon-lang, builds compiler, compiles the tool, runs unit tests and integration smoke tests, tracks binary size.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/axon-pkg-tool.yml'

variables:
  AXON_ENTRY: "src/main.axs"
  AXON_TOOL: "axpm"

`templates/axon-c-tool.yml`

C tool repos (axon-debug). Generic C tool template with gcc build, cppcheck, Python lint (flake8), Python syntax check, and binary size tracking.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/axon-c-tool.yml'

`templates/metrics-collector.yml`

Downloads metrics artifacts from downstream axon-* repos and aggregates them for the axon-www Live Metrics dashboard.

`templates/website-metrics.yml`

Builds the axon-www Astro site and uploads the metrics page. Also runs generate_website_metrics.py for the Live Metrics dashboard.

`templates/perf-thresholds.yml`

Performance regression enforcement for any repo that emits metrics.json. Compares current vs baseline metrics, applies configurable thresholds, posts an MR comment with a markdown report, and optionally fails the pipeline.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/perf-thresholds.yml'

variables:
  METRICS_JOB_NAME: "metrics:examples"
  PERF_THRESHOLD_SIZE: "20"
  PERF_THRESHOLD_COMPILE: "30"

`templates/lint:python-vulture.yml`

Python dead code detection using vulture. Runs only if Python files exist in the repo. allow_failure: true — reports dead code but does not block pipelines.

include:
  - project: 'labs/axon/axon-ci'
    file: '/templates/lint:python-vulture.yml'

variables:
  PYTHON_DIRS: "tools/ scripts/"
  PYTHON_MIN_CONFIDENCE: "80"

Scripts

Script	Purpose
`scripts/check_regression.py`	Compare current vs baseline metrics.json, emit markdown report
`scripts/validate_templates.py`	Static analysis of all templates (YAML structure, jobs, keys)
`scripts/generate_website_metrics.py`	Collect project metrics for axon-www dashboard

Internal CI

axon-ci validates its own templates with its own .gitlab-ci.yml:

Job	Stage	Description
`lint:templates`	lint	Run `validate_templates.py` on all templates
`lint:gitlab-api`	lint	GitLab API lint (requires `GITLAB_API_TOKEN`)
`test:python`	test	Run `pytest scripts/test_*.py`

lint:gitlab-api is marked allow_failure: true and skips when GITLAB_API_TOKEN is not set.

Documentation

Full documentation for templates, scripts, and workflows is in docs/:

Document	Covers
`docs/templates-reference.md`	All 12 templates: jobs, variables, consumer patterns
`docs/perf-thresholds-workflow.md`	End-to-end perf-thresholds.yml consumer guide
`docs/check-regression.md`	check_regression.py CLI, JSON schema, thresholds
`docs/validate-templates.md`	validate_templates.py checks and limitations
`docs/gitlab-api-tokens.md`	GITLAB_API_TOKEN vs CI_JOB_TOKEN
`docs/aggregate_metrics.md`	generate_website_metrics.py CLI and schema
`docs/CONTRIBUTING.md`	How to add templates and scripts

Contributing

See docs/CONTRIBUTING.md for a complete guide to adding templates and scripts.