go-cli-github

README

Go CLI GitHub

This repository is a template for a Go CLI tool or service. It is quite opinionated about security and release engineering, but hopefully in a good way.

It comes pre-configured for integration with GitHub-specific features such as Dependabot security tooling, CodeQL, and branch protection. It also automatically builds and tests your code using GitHub Actions.

Features

• Use GoReleaser to automatically build and create GitHub Releases and Docker images on merge to main.

  • This uses the Conventional Commits Versioner to automatically version each release.

• Lint your commit messages, and your Go, GitHub Action, and Dockerfile code.

• Test Pull Requests using go test.

• Build Docker images from Pull Requests for manual testing and review.

• Static code analysis using CodeQL and Go Report Card.

• Test coverage analysis using Coveralls.

• Security analysis using OpenSSF.

How to use

First set up the GitHub repo

1. Create a new empty GitHub repository.

Then push some code to main:

1. Install gonew and run this command, replacing the last argument with the name of your new module:

   gonew github.com/smlx/go-cli-github@main github.com/smlx/newproject
   

2. Create the git repo and push to main (which will become the default branch):

   cd newproject
   git init .
   git branch -M main
   git remote add origin git@github.com:smlx/newproject.git
   git add .
   git commit -am 'chore: create repository from template'
   git push -u origin main
   

Then customize the code for your repository:

1. Check out a new branch to set up the repo git checkout -b setup

2. Update the code for your project:

   • rename cmd/go-cli-github to cmd/$YOUR_COMMAND
   • rename deploy/go-cli-github to deploy/$YOUR_COMMAND
   • update deploy/$YOUR_COMMAND/Dockerfile
   • update .github/workflows/build.yaml, replacing go-cli-github with $YOUR_COMMAND.
   • update .goreleaser.yml to build cmd/$YOUR_COMMAND
   • update the links at the top of the README

3. Commit and push:

   git add .
   git commit -am 'chore: update template for new project'
   git push -u origin setup
   

4. Open a PR, wait until all the checks go green, then merge the PR.

Configure the repository:

1. Go to repository Settings > General:

   • Disable wiki and projects (unless you plan to use them!)
   • Allow only merge commits for Pull Requests
   • Allow auto-merge
   • Automatically delete head branches

2. Go to repository Settings > Code security and analysis, and enable:

   • Private vulnerability reporting

3. Go to repository Settings > Rules > Rulesets, and import the protect-default-branch.json ruleset.

4. That's it.