Go Repository Template

This is a GitHub repository template for Go. It has been created for ease-of-use for anyone who wants to:

• quickly get into Go without losing too much time on environment setup,
• create a new repoisitory with basic Continous Integration.

It includes:

• continous integration via GitHub Actions,
• build automation via Make,
• dependency management using Go Modules,
• linting with golangci-lint,
• unit testing with race detector and code covarage HTML report,
• auto-tagging via Github Tag Bump GitHub Action,
• releasing using GoReleaser,
• depdendencies scanning and vulnerabilities alerting thanks to Dependabot,
• Visual Studio Code configuration with Go and Remote Container support.

Star this repository if you find it valuable and worth maintaining.

Watch this repository to get notified about new releases, issues, etc.

Usage

1. Click the Use this template button (alt. clone or download this repository).
2. Replace all occurences of golang-templates/seed to your_org/repo_name in all files.
3. Rename folder cmd/seed to cmd/repo_name and update .goreleaser.yml.
4. Update LICENSE and README.md.

Build

• Terminal: make to get help for make targets.
• Visual Studio Code: Terminal → Run Build Task... (CTRL+ALT+B) to execute a fast build.

Release

The release workflow is triggered each time a tag with v prefix is pushed.

This repo uses Github Tag Bump for auto tagging on master branch. Therfore, it automatically triggers the release workflow as well.

• Add #minor to your commit message to bump minor version.
• Add #major to your commit message to bump major version. DANGER! Use it with caution and make sure you understand the consequences. More info: Go Wiki, Go Blog.

Maintainance

Remember to update Go version in .github/workflows, Makefile and devcontainer.json.

Notable files:

• devcontainer.json - Visual Studio Code Remote Container configuration
• .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
• Makefile - Make targets used for development, CI build and .vscode/tasks.json
• 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 .devcontainer and .vscode directories 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.

You can also use the docker make target to run the build using a docker container.

How can I use Make on Windows

Use WSL (Windows Subsystem for Linux) or try Make Windows port.

How can I create a Docker image, deb/rpm/snap package, Homebrew Tap, Scoop App Manifest etc.

Take a look at GoReleaser docs as well as its repo how it is dogfooding its functionality.

How can I create an application installation script

1. Install GoDownloader
2. Execute:

godownloader --repo=your_org/repo_name > ./install.sh

3. Push install.sh to your repository.
4. Add installation instructions to your README.md e.g.:

curl -sSfL https://raw.githubusercontent.com/your_org/repo_name/master/install.sh | sh -s -- -b /usr/local/bin

How can I create a library instead of an application

You can change the .goreleaser.yml to contain:

build:
  skip: true
release:
  github:
  prerelease: auto

Alternativly you can completly remove the usage of GoReleaser if you prefer handcrafted release notes.

Why the code coverage results are not accurate

By default go test records code coverage for the package that is currently tested. If you want to get more accurate (cross-package) coverage, then consider using go-acc. Read more.

Contributing

Simply create an issue or a pull request.