Skip to content

Template repository with deep GitHub integration for a Go CLI tool or service.

License

Notifications You must be signed in to change notification settings

smlx/go-cli-github

Repository files navigation

Go CLI GitHub

Go Reference Release coverage Go Report Card OpenSSF Scorecard OpenSSF Best Practices

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.

  • 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 artifact attestations.

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 [email protected]: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.