hellnet-lib-template

GitHub template for production-ready Go libraries, pre-configured with the canonical Hellnet pattern: CI, linting, pre-commit hooks, dependency automation, and an env-first API.

Click "Use this template" to scaffold a new Go library in seconds.

What's included

• Canonical Hellnet API — the seeded example demonstrates the exact pattern every Hellnet library shares (hellnet-lib-kafka, hellnet-lib-cache, hellnet-lib-telemetry, hellnet-lib-database, hellnet-lib-api):
  • configuration from the environment: every option is exposed as a <LIB>_* environment variable (no HELLNET_ prefix), and .env files load automatically (dev only, self-contained);
  • constructors without context.Context — New, NewFromEnv, MustNew; the runtime captures one context.Background() internally, so no public method takes a ctx;
  • options flow DefaultOptions() → fromEnv(base) → validate();
  • versioning stays v1 forever: signature changes ship as minor/patch releases (never BREAKING CHANGE, never a major bump).
• .golangci.yml — curated linter config (errcheck, staticcheck, gosec, revive, …).
• Lefthook pre-commit hooks (.lefthook.yml): go fmt, go vet, go mod tidy, golangci-lint, gitleaks.
• CI (.github/workflows):
  • pipeline.yml (main): guard-semver (blocks auto-major) + semantic release + lib quality via github.com/guilhermelinosp/templates.
  • pr-check.yml (PR): shellcheck, merge-check, gitleaks, labeler, quality.
  • codeql.yml: go + actions matrix.
• Dependency automation via Dependabot (github-actions + gomod).
• Repo meta: issue/PR/discussion templates, CODEOWNERS, SECURITY.md, CONTRIBUTING.md, FUNDING.yml.

Initialize from this template

After Use this template, clone the new repository and run:

scripts/init-from-template.sh <repo-name> [service-name]   # renames the module, imports and cmd/ (services)
scripts/setup-repo.sh                                      # repo settings, "main" ruleset and CI variable

Then install the Octo STS GitHub App on the repository. No secret is needed: the CI exchanges its OIDC token for a short-lived token (policies in .github/chainguard/).

Quick start

Initialise the repository first (see above); that renames the module path. Then rename the seeded API to your library:

1. Rename the package and envPrefix in golanglibtemplate.go (e.g. KAFKA_); there is no shared HELLNET_ fallback.
2. Replace Options, Greet and the validation rule with your own API.
3. Keep DefaultOptions(), fromEnv, New/MustNew and loadEnvFiles — they are the canonical contract every Hellnet lib exposes.

Configuration

Variable	Purpose	Default
TEMPLATE_NAME	greeting target	World
TEMPLATE_REPEATS	repeat count	1
TEMPLATE_VERBOSE	debug output	false

./.env is loaded automatically by the constructors (dev environments only) — no external loader call needed.

Usage (canonical pattern)

package main

import (
	"fmt"

	"github.com/<you>/<repo>"
)

func main() {
	// env-first: <LIB>_* variables (e.g. TEMPLATE_NAME), .env loaded for you
	c, err := <repo>.New()
	if err != nil {
		panic(err)
	}

	// or fail fast at startup
	c = <repo>.MustNew()

	msg, err := c.Greet("World")
	if err != nil {
		panic(err)
	}
	fmt.Println(msg) // Hello, World!
}

Development

go test -race ./...
go vet ./...
golangci-lint run ./...

Install the git hooks once with lefthook install: they run formatting, vet, tests (with and without -race), build, go mod tidy, lint, govulncheck and a secrets scan. Commits follow Conventional Commits.

CI/CD

Workflow	Trigger	What it does
pr-check	pull request	shellcheck, merge strategy and Conventional Commits (merge-check), Gitleaks, labels and the lib quality gate (module integrity, vet, race tests with coverage, lint, build, dependency review). pr-gate aggregates them and is the required check
pipeline	push to main (ignores .github/**) or manual	semver guard (blocks an automatic major), immutable tag + GitHub Release
codeql	nightly or manual	static analysis (CodeQL)
security	nightly or manual	Gitleaks and Trivy scans
auto-pr	push to feat/** or fix/**	opens the pull request automatically
dependabot-actions-auto-merge	Dependabot pull requests	auto-merges GitHub Actions bumps

The workflows call reusable workflows from templates at @latest. No secret is needed: releases and the other jobs exchange their OIDC token for an Octo STS token (App installed on the repository; policies in .github/chainguard/).

Versioning

Releases and version bumps are derived from Conventional Commits. Hellnet libraries stay on major v1: a change to a public signature ships as a minor or patch release — never a BREAKING CHANGE, never a major bump.

Contributing and license

See CONTRIBUTING.md and SECURITY.md. Licensed under Apache 2.0.