Skip to content

CI Pipeline and Quality Gates

Jump to bottom
William Smith edited this page Jul 13, 2026 · 1 revision

CI Pipeline and Quality Gates

Relevant source files

The following files were used as context for generating this wiki page:

The AXIS Continuous Integration (CI) pipeline is designed to enforce the "Truth Rule" and maintain the single-binary philosophy across heterogeneous hardware environments. It combines standard Go toolchain validation with custom guardrails that verify internal package lifecycles, documentation accuracy, and hardware-specific telemetry collection.

Pipeline Architecture

The quality gates are distributed across three primary GitHub Actions workflows and a suite of local validation scripts located in the hack/ directory.

Core Workflow Components

Workflow Purpose Triggers
ci.yml Primary validation for PRs and merges to main. Push, PR, Merge Group
govulncheck.yml Security scanning for known vulnerabilities in dependencies. Schedule (Weekly), Push, PR
hardware-validation.yml Smoke tests on physical hardware (NixOS/Linux) via self-hosted runners. Schedule (Daily), Push to core paths
release.yml Production artifact generation and version synchronization. Semver Tags (v*.*.*)

Quality Gate Data Flow

The following diagram illustrates how code changes propagate through the quality gates before being accepted into the repository.

CI Pipeline and Guardrail Flow

graph TD
    subgraph "Developer_Environment"
        DEV["Local Code Change"]
        LINT["make lint"]
        TEST["go test -race"]
    end

    subgraph "GitHub_Actions_CI"
        CI_START["ci.yml"]
        GO_TEST["go test -race ./..."]
        COV_GATE["coverage-check.sh"]
        TRUTH_GATE["verify-repo-truth.sh"]
        DOC_GATE["verify-doc-facts.sh"]
        LIFE_GATE["lifecycle-check.go"]
    end

    subgraph "Hardware_Validation_Gate"
        HW_RUNNER["self-hosted runner"]
        HW_BUILD["go build ./cmd/axis"]
        FACT_SMOKE["Facts JSON Smoke Test"]
    end

    DEV --> LINT
    LINT --> TEST
    TEST --> CI_START
    CI_START --> GO_TEST
    GO_TEST --> COV_GATE
    COV_GATE --> TRUTH_GATE
    TRUTH_GATE --> DOC_GATE
    DOC_GATE --> LIFE_GATE
    LIFE_GATE --> HW_RUNNER
    HW_RUNNER --> HW_BUILD
    HW_BUILD --> FACT_SMOKE
Loading

Sources: .github/workflows/ci.yml:1-64, .github/workflows/hardware-validation.yml:1-126, hack/lifecycle-check.go:1-195

Specialized Guardrails

1. Lifecycle Inheritance Check (lifecycle-check.go)

AXIS classifies every internal package into a lifecycle state: Stable, Experimental, Scaffolded, Dormant, InternalOnly, or Deprecated hack/lifecycle-check.go:14-21.

The lifecycle-check.go tool enforces dependency inheritance rules:

  • Stable Integrity: Stable packages (e.g., internal/facts, internal/discovery) are prohibited from transitively importing Experimental or Dormant packages hack/lifecycle-check.go:93-121.
  • Documentation Requirement: Every Experimental package must contain a doc.go file explicitly containing the string "EXPERIMENTAL" hack/lifecycle-check.go:123-141.
  • Dormant Isolation: Dormant packages cannot be imported unless explicitly allow-listed hack/lifecycle-check.go:143-180.

Sources: hack/lifecycle-check.go:24-62, hack/lifecycle-check.go:89-195

2. Repo Truth and Doc Facts

  • verify-repo-truth.sh: Ensures that the codebase does not contain conflicting "truths" regarding its state or configuration github/workflows/ci.yml:54-57.
  • verify-doc-facts.sh: Scans documentation files (e.g., README.md, docs/) to ensure that cited CLI commands, flags, and technical facts match the actual implementation in the source code github/workflows/ci.yml:59-60.

3. Coverage Gates (coverage-check.sh)

The pipeline enforces minimum test coverage thresholds. If a PR reduces coverage below the defined floor, the coverage-check.sh script exits with a non-zero status, blocking the merge github/workflows/ci.yml:46-47.

Hardware Validation Pipeline

Unlike standard software projects, AXIS requires validation against physical hardware to ensure the facts subsystem correctly identifies CPU, RAM, and GPU topologies.

Self-Hosted Runner Strategy

The hardware-validation.yml workflow targets self-hosted runners labeled [self-hosted, Linux, X64, axis, trusted] hardware-validation.yml:30-32. This allows the CI to execute against real hardware rather than virtualized GitHub-hosted environments.

Facts Smoke Test

A critical gate in the hardware pipeline is the Facts JSON Smoke Test:

  1. The runner builds the axis binary hardware-validation.yml:106-110.
  2. It executes ./axis facts --format json hardware-validation.yml:112-117.
  3. It pipes the output to jq to verify that essential hardware telemetry (OS and Architecture) is correctly detected and structured hardware-validation.yml:118-119.

Sources: .github/workflows/hardware-validation.yml:106-119

Release Quality Gates

The release pipeline adds an additional layer of synchronization checks to prevent version mismatch.

Version Synchronization

The validate-version job compares the git tag (e.g., v0.10.0) against the hardcoded Version constant in internal/buildinfo/version.go release.yml:94-129. If they do not match, the release is aborted to ensure the axis version command always reports the correct metadata.

Security and SBOM

  • govulncheck: Runs immediately before the release build to catch last-minute vulnerability disclosures release.yml:143-160.
  • Syft: During the GoReleaser execution, AXIS uses syft to generate a Software Bill of Materials (SBOM) for every platform artifact release.yml:182-202.

Release Pipeline Components

graph LR
    subgraph "Release_Validation"
        V_VER["validate-version"]
        V_SEC["govulncheck"]
        V_TEST["full test suite"]
    end

    subgraph "Artifact_Generation"
        GR["GoReleaser"]
        SYFT["Syft SBOM"]
    end

    V_VER --> GR
    V_SEC --> GR
    V_TEST --> GR
    GR --> SYFT
    SYFT --> REL["GitHub Release Artifacts"]
Loading

Sources: .github/workflows/release.yml:94-214, .github/workflows/govulncheck.yml:1-41

Testing Patterns

The CI environment utilizes specific testing patterns to ensure reliability across network boundaries.

SSH Lifecycle Testing

Because AXIS relies heavily on SSH for remote fact collection internal/transport/ssh.go:83-85, the CI runs ssh_lifecycle_test.go. This test suite spins up an ephemeral sshTestServer to validate:

Race Detection

The go test -race flag is mandatory in both ci.yml ci.yml:41-42 and release.yml release.yml:60-61. This is critical for validating the concurrent node discovery logic in internal/discovery/discovery.go, which uses a semaphore-controlled fan-out pattern internal/discovery/discovery.go:44-51.

Sources: internal/transport/ssh_lifecycle_test.go:31-78, internal/discovery/discovery.go:186-196, .github/workflows/ci.yml:41-42

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally