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.

• Coverage analysis using the go-test-coverage action.

• Security analysis using OpenSSF.

• Signed binary artifacts using Sigstore's cosign.

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
   

3. Create the badges branch for storing the README coverage badge.

   git checkout --orphan badges
   git rm -rf .
   rm -f .gitignore
   echo 'This branch exists only to store the coverage badge in the README on `main`.' > README.md
   git add README.md
   git commit -m 'chore: initialize the badges branch'
   git push origin badges
   

Then customize the code for your repository:

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

2. Update the code for your project:

   • rename cmd/go-cli-github to cmd/$YOUR_COMMAND
   • update .github/workflows/build.yaml, replacing go-cli-github with $YOUR_COMMAND.
   • update .goreleaser.yaml to build cmd/$YOUR_COMMAND
   • update the links at the top of README.md
   • update the contact email in SECURITY.md

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
   • Dependabot
     • Grouped security updates
   • Code Scanning
     • CodeQL analysis > Set up > Default
   • Secret Scanning
     • Push protection

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

That's it.

How to contribute

Issues are welcome.

PRs are also welcome, but keep in mind that this is a very opinionated template, so not all changes will be accepted. PRs also need to ensure that test coverage remains high, and best practices are followed.

How to verify binary signatures

1. Download the three checksums files. They should end in _checksums.txt, _checksums.txt.pem, and _checksums.txt.sig.

2. Verify using cosign. For example:

   cosign verify-blob \
     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
     --certificate-identity=https://github.com/smlx/go-cli-github/.github/workflows/release.yaml@refs/heads/main \
     --signature ./go-cli-github_0.13.0_checksums.txt.sig \
     --cert ./go-cli-github_0.13.0_checksums.txt.pem \
     ./go-cli-github_0.13.0_checksums.txt
   Verified OK