{"id":51192068,"url":"https://github.com/y0f/go-api-scaffolding","last_synced_at":"2026-06-27T16:01:22.782Z","repository":{"id":367228184,"uuid":"1279833145","full_name":"y0f/go-api-scaffolding","owner":"y0f","description":"A production Go REST API scaffold you own: chi, pgx + sqlc, OpenAPI codegen, OpenTelemetry, JWKS auth, migrations, and a generator for new resources.","archived":false,"fork":false,"pushed_at":"2026-06-25T05:03:40.000Z","size":113,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-25T06:11:17.765Z","etag":null,"topics":["agents","ai-agents","api","boilerplate","chi","clean-architecture","go","golang","jwt","microservice","oidc","openapi","opentelemetry","pgx","postgresql","rest-api","scaffold","sqlc","starter-template","testcontainers"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/y0f.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-25T03:48:06.000Z","updated_at":"2026-06-25T05:03:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/y0f/go-api-scaffolding","commit_stats":null,"previous_names":["y0f/go-api-scaffolding"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/y0f/go-api-scaffolding","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0f%2Fgo-api-scaffolding","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0f%2Fgo-api-scaffolding/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0f%2Fgo-api-scaffolding/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0f%2Fgo-api-scaffolding/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/y0f","download_url":"https://codeload.github.com/y0f/go-api-scaffolding/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0f%2Fgo-api-scaffolding/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34859073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-agents","api","boilerplate","chi","clean-architecture","go","golang","jwt","microservice","oidc","openapi","opentelemetry","pgx","postgresql","rest-api","scaffold","sqlc","starter-template","testcontainers"],"created_at":"2026-06-27T16:01:22.000Z","updated_at":"2026-06-27T16:01:22.768Z","avatar_url":"https://github.com/y0f.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.webp\" alt=\"Go\" width=\"200\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ego-api-scaffolding\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  A production Go API foundation you own outright: net/http and chi, pgx with sqlc,\n  an OpenAPI contract, OpenTelemetry, and a generator that keeps the codebase growing.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/y0f/go-api-scaffolding/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/y0f/go-api-scaffolding/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/y0f/go-api-scaffolding\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/y0f/go-api-scaffolding\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/y0f/go-api-scaffolding\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/y0f/go-api-scaffolding.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/go-1.25-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go 1.25\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"MIT\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nA complete Go service with the production concerns already wired in, and a generator\nthat adds new resources in the same shape, so the scaffold keeps working on day 200,\nnot just day 1. Clone it, rename the module, and there is nothing to import at runtime\nand nothing to lock into.\n\n## What is wired in\n\n**HTTP**\n- Standard `net/http` handlers routed by chi, with no framework context.\n- `api/openapi.yaml` is the source of truth. Request validation and the typed\n  server interface are generated from it; CI fails if they drift.\n- RFC 9457 `application/problem+json` errors, each carrying the active trace ID.\n- Readiness-first graceful drain: `/readyz` flips to 503, then in-flight requests\n  bleed off, then the pool closes.\n\n**Data**\n- pgx/v5 with a tuned pool and a transaction helper.\n- sqlc generates type-safe queries from plain SQL checked against the real schema.\n- goose migrations, embedded into the binary and run as an explicit deploy step.\n- A transactional outbox writes events in the same transaction as the state change.\n- Idempotency keys make unsafe requests safe to retry.\n\n**Auth**\n- Bearer tokens verified against JWKS (OIDC) or a configured RSA public key.\n- Role-based access checks in the service layer, with a single seam for OPA or Casbin.\n- In development an ephemeral key is generated and a usable token is logged at startup.\n\n**Observability**\n- OpenTelemetry traces over OTLP and Prometheus metrics at `/metrics` (unauthenticated by convention; restrict it at the network layer in production).\n- slog with `trace_id` and `span_id` on every line, and a handler that redacts\n  secrets like passwords and tokens before they are logged.\n- `/livez` and `/readyz` probes, plus pprof and expvar on a separate guarded port.\n\n**Testing**\n- Integration tests run against a real Postgres via testcontainers, isolated per\n  test by cloning a migrated template database so they are safe to run in parallel.\n- Unit tests cover business logic with no database.\n\n**Supply chain**\n- GitHub Actions pinned to commit SHAs, kept current by Dependabot.\n- `govulncheck` and CodeQL gate the build; an OpenAPI and sqlc drift gate keeps\n  generated code honest.\n- A multi-stage build produces a distroless, non-root, static image.\n- GoReleaser publishes signed binaries (cosign keyless) with an SBOM.\n\n## Quickstart\n\n```bash\ngit clone https://github.com/y0f/go-api-scaffolding\ncd go-api-scaffolding\n\ntask up        # builds and starts Postgres, runs migrations, starts the API\n```\n\nThe API listens on `:8080`. In development it prints a bearer token at startup;\ncopy it from the logs:\n\n```bash\nexport TOKEN=\"\u003ctoken from the api startup log\u003e\"\n\n# List widgets (public)\ncurl -s localhost:8080/v1/widgets\n\n# Create one (requires the token)\ncurl -s -X POST localhost:8080/v1/widgets \\\n  -H \"Authorization: Bearer $TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Idempotency-Key: $(uuidgen)\" \\\n  -d '{\"name\":\"first\"}'\n```\n\nPrefer running the binary directly? Install the toolchain and point it at any\nPostgres:\n\n```bash\ntask setup\ntask migrate\ntask run\n```\n\nSee [`.env.example`](.env.example) for every setting.\n\n## Add a resource\n\nThe generator stamps a new vertical slice (SQL, store, service, handler, test, and\na migration) in the same shape as the example `widget` module:\n\n```bash\ngo run ./cmd/forge add resource Order\n```\n\nIt prints the next steps: register the queries file with sqlc, run `task generate`,\nmount the handler, and apply the migration with `task migrate`. The example slice in\n`internal/modules/widget` shows the full spec-first pattern with auth and idempotency.\n\n## Common tasks\n\n```bash\ntask generate          # regenerate sqlc and OpenAPI code\ntask lint              # golangci-lint v2\ntask test              # unit tests with the race detector and coverage\ntask test:integration  # integration tests against real Postgres (needs Docker)\ntask vuln              # govulncheck\ntask observe           # full stack with OpenTelemetry Collector, Tempo, Prometheus, Grafana\ntask build             # build api, migrate, and forge into ./bin\n```\n\nWith `task observe` running, Grafana is on `http://localhost:3000` with Prometheus\nand Tempo already provisioned, and traces flow from the API through the Collector\ninto Tempo.\n\n## Layout\n\n```\ncmd/api        service entrypoint and composition root\ncmd/migrate    migration runner\ncmd/forge      resource generator\ninternal/      config, server, auth, observability, platform, modules\napi/           the OpenAPI contract\nmigrations/    versioned SQL, embedded into the binaries\ndeployments/   Dockerfile, docker compose, observability configs\ndocs/          architecture notes and ADRs\n```\n\nThe architecture, request flow, and the reasoning behind each choice are in\n[`docs/architecture.md`](docs/architecture.md) and [`docs/adr`](docs/adr).\n\n## For AI agents\n\nAn [`AGENTS.md`](AGENTS.md) describes the build and conventions for coding agents.\nBecause `api/openapi.yaml` is the single source of truth, the operations convert\ncleanly into tool or function schemas for an LLM without hand-written glue.\n\n## Rename the module\n\nThe module path is `github.com/y0f/go-api-scaffolding`. To make it yours:\n\n```bash\ngrep -rl github.com/y0f/go-api-scaffolding . \\\n  | xargs sed -i 's#github.com/y0f/go-api-scaffolding#github.com/you/yourapp#g'\ngo mod edit -module github.com/you/yourapp\ngo mod tidy\n```\n\nThe `FORGE_` environment prefix and the `forge` generator name are independent of\nthe module path; rename them too if you like.\n\n## Verify a release\n\nReleased binaries are signed with cosign keyless signing. Verify the checksums:\n\n```bash\ncosign verify-blob \\\n  --bundle checksums.txt.bundle \\\n  --certificate-identity-regexp 'https://github.com/y0f/go-api-scaffolding' \\\n  --certificate-oidc-issuer https://token.actions.githubusercontent.com \\\n  checksums.txt\n```\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy0f%2Fgo-api-scaffolding","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fy0f%2Fgo-api-scaffolding","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy0f%2Fgo-api-scaffolding/lists"}