Create your project¶
The repository is a GitHub template and a working application at the same time. Creating a project takes two steps: copy it, then run the init tool.
1. Copy the template¶
Press Use this template on the repository page, create your repository and clone it. Its history starts empty.
2. Run the init tool¶
make init runs go run ./tools/init, which asks for the module path, the application
name and each option, with the default in brackets. To run it without questions, pass
-yes and the flags:
billing is ready.
module github.com/acme/billing
kept dev container, example resource, helm chart, metrics, postgres, rate limiting
removed observability stack, sqlite, tracing
Then check the result:
Options¶
| Flag | Default | Effect |
|---|---|---|
-module |
none, required | Go module path of the new project, such as github.com/acme/billing. |
-name |
last element of the module path | Application name: lowercase letters, digits and dashes. Used for the service name, the image and the chart. |
-db |
both |
both, postgres or sqlite. The other driver, its migrations and its Go dependency are deleted. |
-example |
true |
Keep the tasks resource and the resource generator in tools/scaffold. |
-metrics |
true |
Keep Prometheus metrics. |
-tracing |
true |
Keep OpenTelemetry tracing. |
-ratelimit |
true |
Keep rate limiting. |
-observability |
true |
Keep the Prometheus, Grafana and Tempo profile of the Compose file. |
-helm |
true |
Keep the Helm chart. |
-devcontainer |
true |
Keep the dev container. |
-dir |
. |
Directory of the project to initialize. |
-yes |
false |
Do not ask questions. |
Some options depend on others. The tool applies these rules without asking:
-db sqliteremoves the Compose file and the Helm chart, because both assume PostgreSQL.- The observability profile is kept only with PostgreSQL, metrics and tracing all kept.
The generator needs the example
make resource clones the tasks package, so -example=false removes the generator
together with the example. If you want both a clean project and the generator, keep
the example, generate your first resource and then delete internal/tasks yourself.
What it does¶
- Deletes the files owned by the options you turned off.
- Deletes what belongs to the template itself (see below).
- Applies the marker comments to every text file.
- Replaces the module path, the repository name and the application name everywhere, and renames the chart directory.
- Resets the release configuration to version
0.0.0. - Writes a new
README.md. - Runs
go mod tidy, which drops the dependencies of removed options. - Regenerates
configs/env.example, which then lists only the variables that are left.
It refuses to run twice: once the module path is no longer the one of the template, the project counts as initialized.
What is always removed¶
These describe or serve the template, not your project:
tools/init,scripts/and theinitjob of the CI workflowdocs/,overrides/,mkdocs.yml,requirements-docs.txtand the docs workflowCHANGELOG.md,CONTRIBUTING.md,CODE_OF_CONDUCT.md,SECURITY.md.github/ISSUE_TEMPLATE,.github/CODEOWNERS, the Scorecard workflowdeployments/README.md
Kept: the CI, CodeQL and release workflows (without the jobs that test the template),
Dependabot, the pull request template, lefthook.yml, .editorconfig, .golangci.yml
and .goreleaser.yaml.
License
LICENSE is kept. It is the MIT license of the template, with its copyright line.
Add your own copyright line or replace the file with the license of your project.
Marker comments¶
The init tool knows nothing about the code it removes. Optional code is delimited with
comments, and the tool only reads those. A marker at the end of a line covers that line;
a begin/end pair covers a block. This is internal/app/routes.go in the template:
r.Use(middleware.Logger(a.logger))
r.Use(middleware.Recover)
// init:metrics:begin
if a.cfg.Metrics.Enabled {
r.Use(middleware.Metrics(a.registry))
}
// init:metrics:end
r.Use(middleware.SecurityHeaders)
a.auth.Routes(r, loginLimiter)
a.users.Routes(r, a.authn)
a.tasks.Routes(r, a.authn) // init:example
With -metrics=false the block disappears. With metrics kept, only the two marker lines
disappear. Either way the generated project contains no markers. The same syntax works
with # comments in YAML and Makefiles.
| Marker | Removed when |
|---|---|
init:example |
-example=false |
init:metrics |
-metrics=false |
init:otel |
-tracing=false |
init:ratelimit |
-ratelimit=false |
init:sqlite, init:postgres |
the driver is not selected by -db |
init:compose |
-db sqlite |
init:observability |
the observability profile is not kept |
init:helm |
the chart is not kept |
init:template, init:site |
always |
The scaffold: comments in api/openapi.yaml and internal/app belong to the resource
generator. They stay while the example stays and are removed with it.
How this is tested¶
make test-init, which CI runs on every change, generates nine projects:
| Case | Flags |
|---|---|
| defaults | none |
| postgres-only | -db postgres |
| sqlite-only | -db sqlite |
| bare | -db sqlite -example=false -metrics=false -tracing=false -ratelimit=false -devcontainer=false |
| no-example | -example=false |
| no-metrics | -metrics=false |
| no-tracing | -tracing=false |
| no-ratelimit | -ratelimit=false |
| no-extras | -helm=false -observability=false -devcontainer=false |
For each one it checks that no file still mentions the template repository or carries an
init: marker, that gofmt has nothing to change, and that go build, go vet and
go test pass. Projects that keep the example also run the generator and test the new
resource. Set INIT_LINT=1 to lint each generated project as well; this is off by
default because it is slow.
PostgreSQL-only projects
Without SQLite the end-to-end tests need a database. They are skipped unless
TEST_POSTGRES_DSN is set. See Testing.
After the init tool¶
- Add
CONTRIBUTING.mdandSECURITY.mdthat describe your project. - Review
LICENSE. - The release workflow pushes the image to
ghcr.io/<owner>/<repository>of the GitHub repository it runs in. Check.github/workflows/release.ymland.goreleaser.yamlif you release somewhere else. - A generated project is independent of the template. There is no mechanism to pull in later changes; read the changelog and port what you want.