hellnet-worker-template

GitHub template for Go Worker Service projects (Kafka consumers, background workers, etc.).

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

go run ./cmd/worker      # after initialising the repository (see above, `cmd/<service>` once renamed)

Without HELLNET_TELEMETRY_ENDPOINT the worker still runs and prints a tick every 5 s.

Configuration

Variable	Purpose	Default
HELLNET_TELEMETRY_ENDPOINT	OTLP/HTTP collector URL (telemetry runs without exporting when empty)	empty
HELLNET_TELEMETRY_SERVICE	service name reported by telemetry	module name

A .env file next to the binary is loaded when present (internal/env); variables already set in the environment win.

Architecture

cmd/worker/main.go   telemetry -> signal-aware context -> worker loop -> graceful shutdown
internal/env         optional .env loading and typed environment helpers

main.go boots telemetry (telemetry.New), runs workerLoop in a goroutine (a 5 s ticker calling runJob, instrumented as a tick worker span) and, on SIGINT/SIGTERM, cancels the context and waits up to 10 s for the loop to stop. Replace doWork with your job (Kafka consumer, queue polling, scheduled task).

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 Go 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, container image
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/).

Contributing and license

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

Deploy

infrastructure/ tem os manifests (Kustomize) e o pipeline.yml tem o job deployment, que chama o hub tailscale.yml do repositorio templates (OIDC) e sincroniza a Application no ArgoCD. Ao criar um servico a partir deste template, renomeie tudo de uma vez:

NOVO=meu-servico
grep -rl 'hellnet-worker-template' infrastructure .github/workflows/pipeline.yml | xargs sed -i "s/hellnet-worker-template/$NOVO/g"

Depois registre o repositorio em sourceRepos do AppProject e a imagem no ImageUpdater (veja infrastructure/README.md no repositorio templates).