I created this repository for learning and education purposes to help everyone to level up their (open source) projects with good documentation and code/release automation. I spend a lot of time learning and experimenting with different tools and integrations to manage the projects I'm working, thus trying to give some inspiration to save you precious time ๐
Of course there's many ways to automate the release process for your (Go) applications, so consider the examples shared in this repository ONE but not THE way.
Even though this repository puts a focus on building and releasing Go applications, the Github Actions workflows and explanations provided apply to any language/environment.
๐ก Note: Check out this online README
generator to
bootstrap a nice landing page for your users.
This repository shows an end-to-end release management approach for
Go applications using Github
Actions as a pipeline for continuous
integration (CI), goreleaser
for artifact and
release management, ko
to build OCI-compliant
container images, and Kubernetes in Docker
(kind
) for end-to-end testing.
Another goodie: depending on your repository settings and usage, you are likely to stay within the generous Github Actions free tier.
Github Actions is also deeply integrated into Github Packages, a software package hosting service that allows you to host your software packages, e.g. container images.
Even if you don't use Github Actions (yet), I hope the repository still provides value since the tools used here can be used standalone, too.
Based on a trivial Go demo application this repository was built to show the power of Github Actions and related Go tools with the following highlights:
๐ซ ย Add Continuous Integration and end-to-end release automation with
Github Actions ("workflows")
๐ซ ย Add status badges to your project README.md
๐ซ ย Manage your repository (issues) and contributions (PRs) with
automatic greetings and code quality checks
๐ซ ย Produce artifacts for different platforms and software management
tools, e.g. Homebrew, Snaps, etc.
๐ซ ย Automate Github Releases incl. a (templatized) CHANGELOG.md
๐ซ ย Use ko
to not worry about building container images and
Dockerfiles
๐ซ ย Use ko
with kind
for super fast development and end-to-end
testing against real APIs (Kubernetes)
You can grab the resulting artifacts produced by the Github release workflow from the releases page.
As part of this project, a Homebrew formula is maintained and continuously updated as part of the release pipeline. Detailed installation instructions can be found in the dedicated repository.
Quick install via brew
:
brew install embano1/ci-demo-app/demo-app
Multi-arch (platform) OCI-compliant container images are pushed to Github
Container Registry (Github Packages) as
part of the release pipeline. Images are also publicly signed using cosign
and
the sigstore project.
Visit the package page for details.
Example how to run the demo app via docker
:
# print version information
docker run ghcr.io/embano1/ci-demo-app:latest version
version: v0.4.0
commit: c59a1872
# expose default port 8080 to 8080 on the Docker host
# interrupt with CTRL-C
docker run -p 8080:8080 ghcr.io/embano1/ci-demo-app:latest
2022-04-22T08:34:09.432Z INFO ci-demo-app ci-demo-app/main.go:86 running server {"commit": "c59a1872", "version": "v0.4.0", "address": ":8080"}
2022-04-22T08:34:09.561Z DEBUG ci-demo-app ci-demo-app/main.go:119 new request {"commit": "c59a1872", "version": "v0.4.0", "method": "GET", "path": "/api", "client": "172.17.0.1:63376"}
2022-04-22T08:34:15.841Z INFO ci-demo-app ci-demo-app/main.go:79 got signal, attempting graceful shutdown {"commit": "c59a1872", "version": "v0.4.0"}
See Github Release page. A
full CHANGELOG
is also provided.
If you want to see the Github Action workflows used in this repository in action please see this document.
If you are interested in the individual tools used here or you want to learn more about Github Actions, please see this document.
- Golang deep dive, advanced testing, etc. (this repo isn't about teaching Go)
- Advanced 3rd party integration, e.g. Slack, bots to manage issues, comments, etc.
- External (manual) workflow dispatch triggers
- Branch protection and role based access control
- Organization-wide workflows and templates
- Detailed security and repository hardening and guidelines (see notes here)
- Detailed guidelines for writing your custom Github Actions
- Creating/distributing software artifacts other than Go binaries/Homebrew
formulas (see
goreleaser
section in DETAILS to get some inspiration)
A BIG THANK YOU to the Knative community for their endless inspiration ๐