mage-common

Common utilities and libraries for Mage build automation.

Packages

tools

Declarative tool dependency management for Mage projects. Define your tool dependencies in .tools.yaml and let the framework handle installation, version tracking, and execution across Go, download, cargo, gem, npx, and uvx source types.

Full documentation →

Quick Example:

# .tools.yaml
apiVersion: mage-common.randomvariable.co.uk/v1alpha1
kind: ToolConfiguration
spec:
  toolsDir: hack/bin
  tools:
    - name: golangci-lint
      version: v2.9.0
      sources:
        - type: golangci-lint
          url: github.com/golangci/golangci-lint/v2/cmd/golangci-lint

    - name: kubectl
      version: v1.33.1
      sources:
        - type: download
          url: "https://dl.k8s.io/release/{{.Version}}/bin/{{.OS}}/{{.Arch}}/kubectl"
          checksum:
            url: "https://dl.k8s.io/release/{{.Version}}/bin/{{.OS}}/{{.Arch}}/kubectl.sha256"

//go:build mage

package main

import (
    "context"

    "github.com/spf13/pflag"

    "github.com/randomvariable/mage-common/config"
    //mage:import tools
    _ "github.com/randomvariable/mage-common/tools/targets"

    magetools "github.com/randomvariable/mage-common/tools"
)

func init() {
    pflag.Parse()
    config.CleanOSArgs()
}

// Lint runs golangci-lint (auto-installed from .tools.yaml).
func Lint(ctx context.Context) error {
    _, err := magetools.Run(ctx, "golangci-lint", []string{"run", "./..."})
    return err
}

kind

Thin wrapper around sigs.k8s.io/kind for Mage projects. Place a standard kind v1alpha4 Cluster config in .kind-cluster.yaml and use Mage targets to manage the cluster lifecycle. GPU passthrough is supported via a fork that adds GPU and mirror configuration to the v1alpha4 Cluster API.

Quick Example:

# .kind-cluster.yaml
apiVersion: kind.x-k8s.io/v1alpha4
kind: Cluster
name: dev
nodes:
  - role: control-plane
gpu:
  type: nvidia

mage kind:create    # Create cluster
mage kind:status    # Check status
mage kind:delete    # Tear down

config

Standardized Viper-based configuration loading for Mage projects with support for:

• Graceful config.yaml loading with automatic fallback
• Environment variable overrides
• Named command-line arguments (--key=value)
• Mage integration via CleanOSArgs() to prevent flag conflicts
• Structured logging with sensitive value redaction

Full documentation →

Installation

go get github.com/randomvariable/mage-common/tools
go get github.com/randomvariable/mage-common/kind
go get github.com/randomvariable/mage-common/config

Requirements

• Go 1.25 or later
• Mage (for magefiles)

Contributing

Contributions are welcome! Please ensure:

• All tests pass: mage test:run or go test ./...
• Code is linted: mage lint:run or golangci-lint run
• Add tests for new functionality

License

Licensed under the Apache License, Version 2.0.

Copyright 2026 Naadir Jeewa

Versioning

This project follows Semantic Versioning.

Support

For issues and questions:

• GitHub Issues
• Discussions