CI CD Release and Developer Tooling

CI/CD, Release, and Developer Tooling

Relevant source files

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

• .github/workflows/ci.yml
• .github/workflows/claude.yml
• .github/workflows/govulncheck.yml
• .github/workflows/hardware-validation.yml
• .github/workflows/refresh-current-state.yml
• .github/workflows/release.yml
• AGENTS.md
• CONTRIBUTING.md
• Makefile
• hack/pr-review-cycle.sh
• hack/refresh-current-state.sh
• hack/test-lint-failclosed.sh

This section provides an overview of the AXIS automation infrastructure, release engineering, and the local development environment. AXIS utilizes a "fail-closed" philosophy across its tooling to ensure that cluster truth is never misrepresented and that binary artifacts are strictly synchronized with source code state.

The system relies on GitHub Actions for continuous integration, GoReleaser for multi-platform distribution, and a suite of custom shell and Go-based "truth guards" that enforce documentation and metadata consistency.

CI/CD Architecture

The AXIS CI/CD pipeline is divided into three primary functional areas: standard quality gates (CI), security/vulnerability scanning, and hardware-specific validation.

Quality Gates and Validation

The primary CI workflow ci.yml executes on every push and pull request. It enforces a strict "lint-first" policy where gofmt and go vet must pass before tests are executed.

For details on the specific scripts and thresholds used, see CI Pipeline and Quality Gates.

Workflow Interconnectivity

The following diagram illustrates how various workflows and scripts interact to validate a change:

Workflow Execution Graph

graph TD
    subgraph "GitHub Actions"
        CI[".github/workflows/ci.yml"]
        REL[".github/workflows/release.yml"]
        HV[".github/workflows/hardware-validation.yml"]
        GVC[".github/workflows/govulncheck.yml"]
    end

    subgraph "Truth Guards (hack/)"
        VRT["verify-repo-truth.sh"]
        VDF["verify-doc-facts.sh"]
        CC["coverage-check.sh"]
        LC["lifecycle-check.go"]
    end

    CI --> VRT
    CI --> VDF
    CI --> CC
    CI --> LC
    
    REL --> VRT
    REL --> CC
    REL --> GVC
    
    HV --> VRT
    HV --> CC
    HV --> FS["Facts JSON Smoke"]

Loading

Sources: .github/workflows/ci.yml:1-63, .github/workflows/release.yml:38-90, .github/workflows/hardware-validation.yml:39-119

Release Pipeline and Versioning

AXIS releases are strictly governed by the state of internal/buildinfo/version.go. The release pipeline is triggered by semver tags (v*.*.*). A critical "Release Gate" ensures that the git tag matches the hardcoded version string in the source code; if they differ, the release is aborted to prevent metadata drift.

GoReleaser is the authoritative tool for creating GitHub Releases and generating multi-platform binaries for darwin and linux across amd64 and arm64 architectures.

Component	Responsibility
GoReleaser	Compiles binaries, generates changelogs, and uploads assets.
Syft	Generates Software Bill of Materials (SBOM) for every release.
LDFLAGS	Injects Commit, Date, and GoVersion into the binary.
Verify Repo Truth	Ensures README.md and docs/current-state.md match the tag.

For details on the release lifecycle and version synchronization, see Release Pipeline and Versioning.

Sources: .github/workflows/release.yml:94-139, .github/workflows/release.yml:182-214, Makefile:7-11, CONTRIBUTING.md:41-69

Developer Tooling and Workflow

The developer experience is centered around the Makefile, which provides a unified interface for building, installing, and testing the system. AXIS distinguishes between a standard make install (GOPATH-based) and make install-user (targeted at ~/.local/bin), with the latter being the preferred method for modern environments.

Local Quality Control

Developers are expected to run the "PR Review Cycle" helper to simulate CI gates locally before pushing.

Command	Action
make build	Compiles the axis binary with appropriate ldflags.
make lint	Runs gofmt and go vet (fail-closed).
make test-race	Runs the full test suite with the Go race detector enabled.
make coverage	Executes hack/coverage-check.sh to verify per-package gates.

AI-Assisted Development

AXIS includes specific instructions for AI agents (Claude, Copilot) in AGENTS.md and .github/copilot-instructions.md. These rules emphasize the "Truth Rule": agents must never fabricate cluster state and must prioritize observed facts from internal/models/types.go.

For details on contribution guidelines and the package lifecycle taxonomy, see Developer Workflow and Contributing.

Sources: Makefile:15-50, AGENTS.md:11-22, hack/pr-review-cycle.sh:1-18, CONTRIBUTING.md:3-39

Automation Entity Mapping

The following diagram bridges the high-level automation concepts to the specific files and scripts that implement them.

Automation Entity Map

graph LR
    subgraph "Natural Language Space"
        Gate["Quality Gate"]
        Truth["Repo Truth"]
        SBOM["Software Bill of Materials"]
        Linter["Code Linter"]
    end

    subgraph "Code Entity Space"
        Gate --> CC["hack/coverage-check.sh"]
        Gate --> LC["hack/lifecycle-check.go"]
        Truth --> VRT["hack/verify-repo-truth.sh"]
        Truth --> VDF["hack/verify-doc-facts.sh"]
        SBOM --> SYFT["syft (v1.20.0)"]
        Linter --> ML["Makefile: lint target"]
        Linter --> TLF["hack/test-lint-failclosed.sh"]
    end

Loading

Sources: .github/workflows/ci.yml:46-63, .github/workflows/release.yml:182-202, Makefile:36-44, hack/test-lint-failclosed.sh:1-19

---