How to use this repo as a template for your project

I - Introduction

The purpose of this repository is to provide a solid, complete and adaptable base of a Golang-oriented product in a project-managed repository, in order to start a new project with a maximum time saving.

This repository provides commit writting and branch naming conventions, issues and pull request templates, and a custom issues labels preset.

But also CI/CD and release using GitHub Actions, GitHub Container Registry and Docker.

And finally, a simple RESTful API, using Golang, Postgres and Adminer, build with Docker and Docker Compose, using a Makefile.

This repository gathers all the good practices that I have learned over time, both in terms of organization and good maintenance of a project over time as well as in terms of automation, availability and consistancy.

II - Table of content

• I - Introduction
• II - Table of content
• III - Folder structure
• IV - Conventions, templates and labels
  • A - Commit conventions
  • B - Branch naming convention
  • C - Issue template
  • D - Pull request template
  • E - Custom issues labels preset
• V - CI/CD, release and container registry
  • A - CI
  • B - CD
  • C - Release
  • D - Labeler
• VI - Project setup
  • A - Stack
  • B - Makefile
• VII - Contributing
• VIII - License

III - Folder structure

The structure of this project follows these conventions.

• /.github: Conventions, template, labels, ci, cd, settings
• /cmd: main files
• /build: Dockerfiles
• /config: Environment files
• /deploy: Docker Compose files
• /internal: "private" code
• /pkg: "public" code
• /scripts: Makefile bash scripts for setup/install/start

IV - Conventions, templates and labels

A - Commit conventions

tag(scope): #issue_id - message

See COMMIT_CONVENTIONS.md for more informations.

B - Branch naming convention

type_scope-of-the-work

See BRANCH_NAMING_CONVENTIONS.md for more informations.

C - Issue template

See user-story.md for more informations.

D - Pull request template

See pull_request_template.md for more informations.

E - Custom issues labels preset

The labels preset is located at .github/settings.yml.

You can add, edit or remove them. To automatically update these labels, you need to install the "Settings" GitHub app, which will syncs repository settings defined in the file above to your repository.

V - CI/CD, release and container registry

A - CI

The CI workflow is located at .github/workflows/ci.go.yml. It's triggered a each push on all branches.

It consist of:

• install Golang on the VM
• get the dependancies using the cache of other Actions run
• lint the files to check or syntax errors
• build the application

B - CD

The CD workflow is located at .github/workflows/cd.docker.yml. It's triggered a each push on main branch.

It consist of:

• login into the GitHub container registry (ghcr.io)
• build and push the Golang api using the production Dockerfile located at build/pakage/sample-api/Dockerfile

After that, you can check the pushed container at: https://github.com/<username>?tab=packages&repo_name=<repository-name>

IMPORTANT: you need to update the production Dockerfile with your username AND repository name. Otherwise, there will be errors at push:

LABEL org.opencontainers.image.source = "https://github.com/<username>/<repository-name>"

C - Release

The release workflow is located at .github/workflows/md.release.yml. It's triggered manually by user input at: Actions > RELEASE.

IMPORTANT: you need to set the image tag in the action input, for the action to be able to push the docker image and create a release with a specific version. The image tag is a SemVer tag, e.g. 1.0.2.

It consist of:

• check if the environment match the branch
• do the CD (docker) action again, but with a specific image tag
• create a release with the same tag, filled with the generated changelog as closed issues since the last release

After that, you can check the release at https://github.com/<username>/<repository-name>/releases.

D - Labeler

The labeler workflow consists in assigning specific labels on pull requests according to the files that have been modified in the commits attached to this pull request.

VI - Project setup

The project use Docker and Docker Compose to build and run local and distant images in our workspace.

A - Stack

All the images use the same network, more informations at docker-compose.yml

CONTAINER	PORT	IMAGE
GOLANG	3333:3333	build/pakage/sample-api/Dockerfile
ADMINER	3334:8080	build/package/adminer/Dockerfile
POSTGRES	5432:5432	postgres:latest

Adminer is a GUI that allows us to manage your database by permetting to to create, edit, delete the different entities, tables, etc.

B - Makefile

TL;DR

make setup-env start logs

make help

Display informations about other commands.

make setup-env

Copy the sample environment files.

make start

Up the containers with full cache reset to avoid cache errors.

make stop

Down the containers.

make logs

Display and follow the logs.

make lint

Lint the Go files using gofmt.

VII - Contributing

See CONTRIBUTING.md for more informations.

VIII - License

Under MIT license.