🚀  go-template

From Zero to Go Hero: Pre-wired Template for Modern Libraries

CI / CD		Quality
Security		Community

Project Navigation

🚀 Installation	🧪 Examples & Tests	📚 Documentation
🤝 Contributing	🛠️ Code Standards	⚡ Benchmarks
🤖 AI Usage	⚖️ License	👥 Maintainers

🧩 What's Inside

go-template is a plug-and-play scaffold that lets you skip the boilerplate and jump straight to building your Go library. Clone it, rename a few placeholders, and you instantly inherit a production-grade setup:

• 📚 Go Best Practices & Examples Includes idiomatic Go patterns, table-driven tests, benchmarks, example functions, and fuzz tests—demonstrating how to write robust, maintainable, and production-grade Go code.

• ⚡ Zero-config CI/CD GitHub Actions run tests, upload coverage, and enforce linting on every push—so you never forget to run the checks.

• 🛠️ One-command via MAGE-X magex test, magex lint, magex bench, and more—common tasks stay muscle-memory simple.

• 🚢 Automated Releases GoReleaser cuts signed, versioned artifacts the moment you push a tag—shipping new versions becomes a 10-second ritual.

• 🛡️ Security & Supply-chain Guardrails Dependabot, Nancy, govulncheck, CodeQL, OpenSSF Scorecard and gitleaks give early warnings before bad things reach production.

• 🎨 Style & Quality Enforcement golangci-lint with 50+ linters and gofumpt keeps the codebase clean and idiomatic - no bikeshedding required.

• 🤖 AI-Friendly Policies AGENTS.md, CLAUDE.md, ensure ChatGPT, Claude & Gemini follow the same house rules.

• 🌍 Community-Ready Meta Issue/PR templates, CODEOWNERS, label sync, and a welcome bot to show contributors exactly how to get involved.

🚀 Quick Wins

• Clone → Tag → Release: Go from idea to a published version in under five minutes.
• Works Everywhere: macOS, Linux, Windows (maybe lol), ARM64 – fully reproducible builds.
• Battery-Included Examples: ready-to-run demos, benchmarks, fuzz and race tests.
• Flexible, Not Fragile: swap or remove any piece without breaking the whole.

Tip: Run magex help right after cloning to see every command the template unlocks.

---

🛠 Template Kick-Off Guide (3 Easy Steps)

(delete this section once your project is initialized)

1) Clone or "Use this template"

git clone https://github.com/mrz1836/go-template.git my-lib && cd my-lib

... or click Use this template on GitHub and create a new repo.

2) Install MAGE-X build tool and run the installation script

go install github.com/mrz1836/mage-x/cmd/magex@latest

# Run the install script to customize the project for your organization
magex InstallTemplate owner=yourorg repo=yourproject

Example:

# For GitHub user "acme" creating a project called "awesome-api"
magex InstallTemplate owner=acme repo=awesome-api

What does that command do?

1. Finds & replaces names across 70+ files

   • mrz1836/go-template → yourorg/yourproject
   • go-template → yourproject
   • mrz1836 → yourorg

2. Cleans up template artifacts

   • Removes the default social-share image so you can add your own
   • Updates module paths in go.mod
   • Fixes all GitHub badges and links

3. Provides helpful feedback

   • Shows exactly which files were modified
   • Gives you next steps to review and commit changes

3) Touch up metadata

Edit the highlighted files so they match your project:

• LICENSE
  • Update the year and your name or organization
• README.md
  • Remove the "remove-this-section" block in this file
  • Modify the "About" section to describe your library
• .github/SECURITY.md
  • Update the security policy to match your project's needs
• .github/FUNDING.yml
  • If you want to accept funding, add your funding links here
• .goreleaser.yml
  • Modify settings for Slack, Discord, Twitter, or Reddit if you want to announce releases
• CODEOWNERS
  • Adjust rules for code ownership if needed

Give it a spin!

Push your initial commit and run magex version:bump push=true bump=minor and the CI/CD pipeline will take it from there. 🚀

┌──────────────────────────────────────────────────────────────────────────────────────────┐
│                                                                                          │
│           MR. Z'S GO-TEMPLATE – YOUR README STARTS RIGHT AFTER THIS BANNER               │
│                                                                                          │
└──────────────────────────────────────────────────────────────────────────────────────────┘
                                         ⬇ ⬇ ⬇

📦 Installation

go-template requires a supported release of Go.

go get -u github.com/mrz1836/go-template

Get the MAGE-X build tool for development:

go install github.com/mrz1836/mage-x/cmd/magex@latest

📚 Documentation

• API Reference – Dive into the godocs at pkg.go.dev/github.com/mrz1836/go-template
• Usage Examples – Browse practical patterns either the examples directory or view the example functions
• Benchmarks – Check the latest numbers in the benchmark results
• Test Suite – Review both the unit tests and fuzz tests (powered by testify)

Good to know: go-template ships with zero runtime dependencies. The only external package we use is testify and magefile — and that's strictly for tests and dev.

Repository Features

This repository includes 25+ built-in features covering CI/CD, security, code quality, developer experience, and community tooling.

View the full Repository Features list →

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump push=true bump=patch branch=master

This process ensures consistent, repeatable releases with properly versioned artifacts and metadata.

Pre-commit Hooks

Set up the Go-Pre-commit System to run the same formatting, linting, and tests defined in AGENTS.md before every commit:

go install github.com/mrz1836/go-pre-commit/cmd/go-pre-commit@latest
go-pre-commit install

The system is configured via modular env files in .github/env/ and provides 17x faster execution than traditional Python-based pre-commit hooks. See the complete documentation for details.

GitHub Workflows

All workflows are driven by modular configuration in .github/env/ — no YAML editing required.

View all workflows and the control center →

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any tools managed by MAGE-X. It is the recommended way to keep your development environment and CI in sync with the latest versions.

Build Commands

View all build commands

magex help

🧪 Examples & Tests

All unit tests and examples run via GitHub Actions and use Go version 1.24.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

Benchmark Results

Benchmark	Iterations	ns/op	B/op	allocs/op
Greet	21,179,739	56.59	40	2

These benchmarks reflect fast, allocation-free lookups for most retrieval functions, ensuring optimal performance in production environments. Performance benchmarks for the core functions in this library, executed on an Apple M1 Max (ARM64).

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Usage & Assistant Guidelines

Read the AI Usage & Assistant Guidelines for details on how AI is used in this project and how to interact with the AI assistants.

👥 Maintainers

MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

📝 License