Skip to content

Release Pipeline and Versioning

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

Release Pipeline and Versioning

Relevant source files

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

The AXIS release pipeline is a fully automated system designed to produce secure, multi-platform binaries and Software Bill of Materials (SBOMs). It enforces strict synchronization between Git metadata and internal source constants to ensure that the "Truth Rule" extends to the binary's own identity.

Pipeline Architecture and Toolchain

The pipeline utilizes GoReleaser for orchestration, syft for SBOM generation, and GitHub Actions for CI/CD gating.

Release Workflow Data Flow

The following diagram illustrates the transition from a Git tag to a published release, highlighting the validation gates and artifact generation.

Title: Release Pipeline Data Flow

graph TD
    ["git push tag v*.*.*"] --> [".github/workflows/release.yml"]
    
    subgraph "Validation Gates"
        [".github/workflows/release.yml"] --> ["Test Gate (go test -race)"]
        [".github/workflows/release.yml"] --> ["Security Scan (govulncheck)"]
        [".github/workflows/release.yml"] --> ["Version Validation (validate-version)"]
    end
    
    ["Version Validation (validate-version)"] -- "Matches" --> ["GoReleaser (release job)"]
    ["Version Validation (validate-version)"] -- "Mismatch" --> ["Pipeline Failure"]
    
    subgraph "Artifact Generation"
        ["GoReleaser (release job)"] --> ["Multi-platform Binaries (darwin/linux)"]
        ["GoReleaser (release job)"] --> ["syft (SBOM generation)"]
        ["GoReleaser (release job)"] --> ["Checksums (sha256sum)"]
    end
    
    ["Multi-platform Binaries (darwin/linux)"] --> ["GitHub Release Assets"]
    ["syft (SBOM generation)"] --> ["GitHub Release Assets"]
    ["Checksums (sha256sum)"] --> ["GitHub Release Assets"]
Loading

Sources: .github/workflows/release.yml:11-168, .goreleaser.yml:7-65

Version Synchronization

AXIS maintains a single source of truth for its versioning. The release pipeline enforces that the Git tag (e.g., v0.10.0) exactly matches the Version constant defined in the source code.

The Version Validation Gate

The validate-version job in the release workflow extracts the version string from internal/buildinfo/version.go and compares it against the ${{ github.ref_name }}. If the tag is v0.10.0, the source must contain Version = "0.10.0".

Build Metadata Injection

GoReleaser injects build-time metadata into the internal/buildinfo package using ldflags. This ensures that axis --version provides accurate provenance data.

Flag Variable Value
-X internal/buildinfo.Commit Short Git Commit Hash
-X internal/buildinfo.Date Build Timestamp
-X internal/buildinfo.GoVersion Go Toolchain Version

Sources: .github/workflows/release.yml:94-139, .goreleaser.yml:24-28

Binary Production and Security

AXIS produces statically linked binaries for darwin and linux on both amd64 and arm64 architectures.

Supply Chain Security

  1. SBOM Generation: The pipeline installs syft to generate a Software Bill of Materials for every archive, providing transparency into the dependency tree .github/workflows/release.yml:182-202.
  2. Checksums: A checksums.txt file is generated using the SHA-256 algorithm, allowing users to verify the integrity of downloaded binaries .goreleaser.yml:52-54.
  3. Reproducible Builds: mod_timestamp is set to the commit timestamp to aid in build reproducibility .goreleaser.yml:36.

Hardware Validation

Before a release is finalized, the hardware-validation.yml workflow runs smoke tests on self-hosted runners. This includes:

Sources: .goreleaser.yml:29-37, .github/workflows/hardware-validation.yml:30-119

The axis update Command

The axis update command provides a built-in mechanism for users to synchronize their local binary with the latest GitHub release.

Update Implementation Details

Title: Update Command Logic

graph TD
    ["axis update"] --> ["fetchLatestRelease()"]
    ["fetchLatestRelease()"] --> ["GitHub API (api.github.com)"]
    ["GitHub API (api.github.com)"] --> ["compareReleaseVersions()"]
    
    subgraph "internal/versioncmp"
        ["compareReleaseVersions()"] --> ["Version Logic"]
    end
    
    ["Version Logic"] -- "Newer Available" --> ["installRelease()"]
    ["Version Logic"] -- "Up to Date" --> ["Exit"]
    ["Version Logic"] -- "Local is Newer" --> ["Refuse Downgrade"]
    
    subgraph "Installation (installRelease)"
        ["installRelease()"] --> ["downloadReleaseBinary()"]
        ["downloadReleaseBinary()"] --> ["verifyChecksum()"]
        ["verifyChecksum()"] --> ["replaceExecutable()"]
    end
Loading

Key Functions and Behaviors

  • runUpdate: The main entry point that coordinates version checking and installation .cmd/axis/update.go:81-144.
  • findAxisBinaries: Discovers all instances of the axis binary in the user's PATH. If the --all flag is used, it attempts to update every discovered instance .cmd/axis/update.go:153-197.
  • replaceExecutable: Performs an in-place binary swap. It is designed to be safe even if the binary is currently running .cmd/axis/update.go:283-305.
  • Safety Gating: The updater refuses to perform in-place updates if the binary is managed by a package manager (indicated by buildinfo.UpdateManagedBy) .cmd/axis/update.go:137-140.

Dry-Run and Verification

Users can run axis update --check to see if an update is available without performing any filesystem mutations .cmd/axis/update.go:105-121.

Sources: cmd/axis/update.go:47-305, cmd/axis/update_test.go:48-180

AXIS Wiki

Architecture Artifacts

DeepWiki

Clone this wiki locally