Quickstart: demo Go reference project

In the project you will find a commented CircleCI configuration file .circleci/config.yml. This file shows best practice for using CircleCI 2.0 with Go projects.

Pre-built CircleCI Docker images

We recommend using a CircleCI pre-built image that comes pre-installed with tools that are useful in a CI environment. You can select the version you need from Docker Hub: https://hub.docker.com/r/circleci/golang/. The demo project uses an official CircleCI image.

Build the demo project yourself

A good way to start using CircleCI is to build a project yourself. Here’s how to build the demo project with your own account:

Fork the project on GitHub to your own account

Go to the Add Projects page in CircleCI and click the Build Project button next to the project you just forked

To make changes you can edit the .circleci/config.yml file and make a commit. When you push a commit to GitHub, CircleCI will build and test the project.

Config Walkthrough

This section explains the commands in .circleci/config.yml

We always start with the version.

version: 2

Next, we have a jobs key. Every config file must have a ‘build’ job. This is the only job that will be automatically picked up and run by CircleCI.

In the job, we specify a working_directory. Go is very strict about the structure of the Go Workspace, so we’ll need to specify a path that satisfies those requirements.

The checkout step will default to the working_directory we have already defined.

steps:
- checkout

Next we create a directory for collecting test results

- run: mkdir -p $TEST_RESULTS

And install the Go implementation of the JUnit reporting tool. This is another good candidate to be preinstalled in primary container.

- run: go get github.com/jstemmer/go-junit-report

Both containers (primary and postgres) start simultaneously, however Postgres may require some time to get ready and if our tests start before that the job will fail. So it’s good practice to wait until dependent services are ready. Here we have only Postgres, so we add this step:

Our project uses make for building and testing (you can see Makefilehere), so we can just run make test. In order to collect test results and upload them later (read more about test results in the Project Tutorial) we’re using go-junit-report:

make test | go-junit-report > ${TEST_RESULTS}/go-test-report.xml

In this case all output from make test will go straight into go-junit-report without appearing in stdout. We can solve this by using two standard Unix commands tee and trap. The first one allows us to duplicate output into stdout and somewhere else (read more). The second one allows us to specify some command to be executed on script exit (read more). So we can do:

To start the service we need to build it first. After that we use the same environment variables as we did in the testing step for the service to start. We’re using background: true to keep the service running and proceed to the next step where we use curl to validate it successfully started and is responding to our request.

Finally, let’s specify a path to store the results of the tests.

- store_test_results:
path: /tmp/test-results

Success! You just set up CircleCI 2.0 for a Go app. Check out our project’s build page to see how this looks when building on CircleCI.

If you have any questions about the specifics of testing your Go application, head over to our community forum for support from us and other users.

Help make this document better

This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.