go-makefile-maker

go-makefile-maker

Generates a Makefile and GitHub workflows for your Go application:

• Makefile follows established Unix conventions for installing and packaging, and includes targets for vendoring, running tests and checking code quality.
• GitHub Workflows use GitHub Actions to lint, build, and test your code. Additionally, you can enable workflows for checking your codebase for security issues (e.g. CodeQL code scanning), spelling errors, and missing license headers.

Installation

The easiest way to get go-makefile-maker is: go install github.com/sapcc/go-makefile-maker@latest.

We also support the usual Makefile invocations: make, make check, and make install. The latter understands the conventional environment variables for choosing install locations: DESTDIR and PREFIX.

You usually want something like make && sudo make install PREFIX=/usr/local.

Usage

Put a Makefile.maker.yaml file in your Git repository's root directory, then run the following to generate Makefile and GitHub workflows:

$ go-makefile-maker

go-makefile-maker also generates a help target for usage info:

$ make help

In addition to the Makefile, you should also commit the Makefile.maker.yaml file so that your users don't need to have go-makefile-maker installed.

Configuration

go-makefile-maker requires a config file (Makefile.maker.yaml) in the YAML format.

Take a look at go-makefile-maker's own config file for an example of what a bare minimum config could like.

The config file has the following sections:

• binaries
• coverageTest
• variables
• vendoring
• golangciLint
• spellCheck
• renovate
• verbatim
• githubWorkflow
  • githubWorkflow.global
  • githubWorkflow.ci
  • githubWorkflow.securityChecks
  • githubWorkflow.license
  • githubWorkflow.spellCheck

binaries

binaries:
  - name: example
    fromPackage: ./cmd/example
    installTo: bin/
  - name: test-helper
    fromPackage: ./cmd/test-helper

For each binary specified here, a target will be generated that builds it with go build and puts it in build/$NAME. The fromPackage is a Go module path relative to the directory containing the Makefile.

If installTo is set for at least one binary, the install target is added to the Makefile, and all binaries with installTo are installed by it. In this case, example would be installed as /usr/bin/example by default, and test-helper would not be installed.

coverageTest

coverageTest:
  only: '/internal'
  except: '/test/util|/test/mock'

When make check runs go test, it produces a test coverage report. By default, all packages inside the repository are subject to coverage testing, but this section can be used to restrict this. The values in only and except are regexes for grep -E. Since only entire packages (not single source files) can be selected for coverage testing, the regexes have to match package names, not on file names.

variables

variables:
  GO_BUILDFLAGS: '-mod vendor'
  GO_LDFLAGS: ''
  GO_TESTENV: ''

Allows to override the default values of Makefile variables used by the autogenerated recipes. This mechanism cannot be used to define new variables to use in your own rules; use verbatim for that. By default, all accepted variables are empty. The only exception is that GO_BUILDFLAGS defaults to -mod vendor when vendoring is enabled (see below).

A typical usage of this is to give compile-time values to the Go compiler with the -X linker flag:

variables:
  GO_LDFLAGS: '-X github.com/foo/bar.Version = $(shell git describe --abbrev=7)'

GO_TESTENV can contain environment variables to pass to go test:

variables:
  GO_TESTENV: 'POSTGRES_HOST=localhost POSTGRES_DATABASE=unittestdb'

vendoring

vendoring:
  enabled: false

Set vendoring.enabled to true if you vendor all dependencies in your repository. With vendoring enabled:

1. The default for GO_BUILDFLAGS is set to -mod vendor, so that build targets default to using vendored dependencies. This means that building binaries does not require a network connection.
2. The make tidy-deps target is replaced by a make vendor target that runs go mod tidy && go mod verify just like make tidy-deps, but also runs go mod vendor. This target can be used to get the vendor directory up-to-date before commits.

golangciLint

golangciLint:
  createConfig: false
  errcheckExcludes:
    - io/ioutil.ReadFile
    - io.Copy(*bytes.Buffer)
    - io.Copy(os.Stdout)
    - (*net/http.Client).Do

The make check and make static-check targets use golangci-lint to lint your code.

If createConfig is set to true then go-makefile-maker will create a config file (.golangci.yaml) for golangci-lint and keep it up-to-date (in case of new changes). This config file enables extra linters in addition to the default ones and configures various settings that can improve code quality.

Additionally, if createConfig is true, you can specify a list of functions to be excluded from errcheck linter in errcheckExcludes field. Refer to errcheck's README for info on the format for function signatures that errcheck accepts.

Take a look at go-makefile-maker's own golangci-lint config file for an up-to-date example of what the generated config would look like.

spellCheck

spellCheck:
  ignoreWords:
    - example
    - exampleTwo

golangci-lint (if golangciLint.createConfig is true) and the spell check GitHub workflow (githubWorkflow.spellCheck) use misspell to check for spelling errors.

If spellCheck.ignoreWords is defined then both golangci-lint and spell check workflow will give this word list to misspell so that they can be ignored during its checks.

renovate

renovate:
  enabled: true
  goVersion: 1.17

Generate RenovateBot config to automatically create pull requests with dependency updates.

Optionally overwrite go version with goVersion if go.mod detection fails.

verbatim

verbatim: |
  run-example: build/example
    ./build/example example-config.txt

This field can be used to add your own definitions and rules to the Makefile. The text in this field is copied into the Makefile mostly verbatim, with one exception: Since YAML does not like tabs for indentation, we allow rule recipes to be indented with spaces. This indentation will be replaced with tabs before writing it into the actual Makefile.

githubWorkflow

The githubWorkflow section holds configuration options that define the behavior of various GitHub workflows.

Hint: You can prevent the workflows from running by including [ci skip] in your commit message (more info).

githubWorkflow.global

This section defines global settings that apply to all workflows. If the same setting is supported by a specific workflow and is defined then that will take override its global value.

global:
  defaultBranch: dev
  goVersion: 1.17
  ignorePaths:
    - "README.md"
    - "docs/**"

defaultBranch specifies the Git branch on which push actions will trigger the workflows. This does not affect pull requests, they will automatically trigger all workflows regardless of which branch they are working against. go-makefile-maker will automatically run git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@' and use its value by default.

goVersion specifies the Go version that is used for jobs that require Go. go-makefile-maker will automatically retrieve the Go version from go.mod file and use that by default.

ignorePaths specifies a list of filename patterns. Workflows will not trigger if a path name matches a pattern in this list. More info and filter pattern cheat sheet. This option is not defined by default.

Note: ignorePaths does not apply to CodeQL workflow, it is exempt from this global setting because a workflow's paths-ignore option can prevent Code Scanning annotating new alerts in your pull requests.

githubWorkflow.ci

This workflow:

• checks your code using golangci-lint
• ensures that your code compiles successfully
• runs tests and generates test coverage report
• uploads the test coverage report to Coveralls

ci:
  enabled: true
  runOn:
    - macos-latest
    - ubuntu-latest
    - windows-latest
  coveralls: true
  postgres:
    enabled: true
    version: 12
  ignorePaths: []

runOn specifies a list of machine(s) to run the build and test jobs on (more info). You can use this to ensure that your build compilation and tests are successful on multiple operating systems. Default value for this is ubuntu-latest.

If coveralls is true then your test coverage report will be uploaded to Coveralls. Make sure that you have enabled Coveralls for your GitHub repo beforehand.

If postgres.enabled is true then a PostgreSQL service container will be added for the test job. You can connect to this PostgreSQL service at localhost:54321 with postgres as username and password (More info). postgres.version specifies the Docker Hub image tag for the postgres image that is used for this container. By default 12 is used as image tag.

ignorePaths is the same as global.ignorePaths and can be used to override it for this particular workflow.

githubWorkflow.securityChecks

If securityChecks is enabled then it will generate two workflows:

• CodeQL workflow will run CodeQL, GitHub's industry-leading semantic code analysis engine, on your source code to find security vulnerabilities. You can see the security report generated by CodeQL under your repo's Security tab.

  In addition to running the workflow when new code is pushed, this workflow will also run on a weekly basis (every Monday at 07:00 AM) so that existing code can be checked for new vulnerabilities.

• dependency-review workflow will scan your pull requests for dependency changes and will raise an error if any new dependencies have existing vulnerabilities.

securityChecks:
  enabled: true

githubWorkflow.license

This workflow ensures that all your source code files have a license header. It uses addlicense for this.

license:
  enabled: true
  patterns:
    - "*.go"
    - "internal/"
  ignorePaths: []

patterns specifies a list of filename patterns to check. Directory patterns are scanned recursively. See addlicense's README for more info.

ignorePaths is the same as global.ignorePaths and can be used to override it for this particular workflow.

Hint: you can also addlicense to add license headers to Go files by running make license-headers.

githubWorkflow.spellCheck

This workflow uses misspell to check your repo for spelling errors. Unlike golangci-lint that only runs misspell on .go files, this workflow will run misspell on your entire repo.

spellCheck:
  enabled: true
  ignorePaths: []

ignorePaths is the same as global.ignorePaths and can be used to override it for this particular workflow.