Go Repository Template
⭐ Star
this repository if you find it valuable and worth maintaining.
👁 Watch
this repository to get notified about new releases, issues, etc.
Description
This is a GitHub repository template for a Go application. You can use it:
- to create a new repoisitory with automation and environment setup,
- as reference when improving automation for an existing repository.
It includes:
- continuous integration via GitHub Actions,
- build automation via Make,
- dependency management using Go Modules,
- code formatting using gofumpt,
- linting with golangci-lint and misspell,
- unit testing with race detector, code covarage HTML report and Codecov report,
- releasing using GoReleaser,
- dependencies scanning and updating thanks to Dependabot,
- security code analysis using CodeQL Action,
- Visual Studio Code configuration with Go support.
Usage
- Sign up on Codecov and configure Codecov GitHub Application for all repositories.
- Click the
Use this template
button (alt. clone or download this repository). - Replace all occurrences of
golang-templates/seed
toyour_org/repo_name
in all files. - Replace all occurrences of
seed
torepo_name
in Dockerfile. - Update the following files:
Setup
Below you can find sample instructions on how to set up the development environment. Of course, you can use other tools like GoLand, Vim, Emacs. However, take notice that the Visual Studio Go extension is officially supported by the Go team.
- Install Go.
- Install Visual Studio Code.
- Install Go extension.
- Clone and open this repository.
F1
->Go: Install/Update Tools
-> (select all) -> OK.
Build
Terminal
make
- execute the build pipeline.make help
- print help for the Make targets.
Visual Studio Code
F1
→ Tasks: Run Build Task (Ctrl+Shift+B or ⇧⌘B)
to execute the build pipeline.
Release
The release workflow is triggered each time a tag with v
prefix is pushed.
CAUTION: Make sure to understand the consequences before you bump the major version. More info: Go Wiki, Go Blog.
Maintenance
Notable files:
- .github/workflows - GitHub Actions workflows,
- .github/dependabot.yml - Dependabot configuration,
- .vscode - Visual Studio Code configuration files,
- .golangci.yml - golangci-lint configuration,
- .goreleaser.yml - GoReleaser configuration,
- Dockerfile - Dockerfile used by GoReleaser to create a container image,
- Makefile - Make targets used for development, CI build and .vscode/tasks.json,
- go.mod - Go module definition,
- tools.go - build tools.
FAQ
Why Visual Studio Code editor configuration
Developers that use Visual Studio Code can take advantage of the editor configuration. While others do not have to care about it. Setting configs for each repo is unnecessary time consuming. VS Code is the most popular Go editor (survey) and it is officially supported by the Go team.
You can always remove the .vscode directory if it really does not help you.
Why GitHub Actions, not any other CI server
GitHub Actions is out-of-the-box if you are already using GitHub. Here you can learn how to use it for Go.
However, changing to any other CI server should be very simple, because this repository has build logic and tooling installation in Makefile.
How can I build on Windows
Install tdm-gcc
and copy C:\TDM-GCC-64\bin\mingw32-make.exe
to C:\TDM-GCC-64\bin\make.exe
.
Alternatively, you may install mingw-w64
and copy mingw32-make.exe
accordingly.
Take a look here, if you have problems using Docker in Git Bash.
You can also use WSL (Windows Subsystem for Linux) or develop inside a Remote Container. However, take into consideration that then you are not going to use "bare-metal" Windows.
Consider using goyek for creating cross-platform build pipelines in Go.
How can I customize the release
Take a look at GoReleaser docs as well as its repo how it is dogfooding its functionality. You can use it to add deb/rpm/snap packages, Homebrew Tap, Scoop App Manifest etc.
If you are developing a library and you like handcrafted changelog and release notes, you are free to remove any usage of GoReleaser.
Contributing
Feel free to create an issue or propose a pull request.
Follow the Code of Conduct.