An example of a golang-based monorepo.
Branch: master
Clone or download
Latest commit 5020f73 Jan 14, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci update golang version Nov 6, 2018
cmd/samplecmd Update go version Jan 14, 2019
pkg/util Cleanup util. Feb 6, 2018
services/samplesvc Update go version Jan 14, 2019
vendor initial support for go modules Sep 19, 2018
LICENSE Initial commit Feb 6, 2018
Makefile Add makefile. Feb 6, 2018 Update Jan 14, 2019 rename build script Sep 19, 2018
go.mod initial support for go modules Sep 19, 2018
go.sum initial support for go modules Sep 19, 2018



This is an example of a golang-based monorepo. It has the following features:

  • Only build the services or cmds that are updated.
  • Build all services and/or cmds that are affected by changes in common codes (i.e. pkg).
  • Build all services and/or cmds that are affected by changes in vendor codes.

For now, only CircleCI 2.0 is supported. But since it uses bash scripts and Makefiles, it should be fairly straightforward to port to TravisCI or AppVeyor.

At the moment, CI is setup to use Go1.11[.x] with GO111MODULE=on and GOFLAGS=-mod=vendor environment variables enabled during build. See sample dockerfile for more details.

How does it work

During CircleCI builds, the script iterates the updated files within the commit range (CIRCLE_COMPARE_URL environment variable in CircleCI) or the changed files within a single commit (when the value is not a valid range), excluding hidden files, pkg, and vendor folders. It will then try to walk up the directory path until it can find a Makefile (excluding root Makefile). Once found, the root Makefile will include that Makefile and call the custom rule as target, thus, initiating the build.

When the changes belong to either pkg or vendor, the script will then try to determine the services (and cmds) that have dependencies using the go list command. All dependent services will then be built using the same process described above.

Directory structure

  • services/ - Basically, long running services.
  • cmd/ - CLI-based tools that are not long running.
  • pkg/ - Shared codes, or libraries common across the repo.
  • vendor/ - Third party codes from different vendors.

Although we have this structure, there is no limitation into where should you put your services/cmds. Any subdirectory structure is fine as long as a Makefile is provided.

How to add a service/cmd

A reference template named samplesvc is provided. Basically, these are the things that you need to do:

  • Create a new directory for your service under services/ or tool under cmd/. You may copy the samplesvc contents to your new directory.
  • Update the dockerfile inside your new service directory. Note that during build, this dockerfile is copied to the root directory.
  • Update the Makefile with your own values. You need to at least update the MODULE variable with your service name. The only required rule is the custom part so you may need to change that as well (i.e. name of the dockerfile used in docker build).
  • [Optional] Update the script for your deployment needs.