Go is an open-source programming language, backed by Google, that makes it easy to build simple, reliable, and efficient software. Go is gaining popularity because it was built for developing distributed systems that C and Java have limitations around. Go’s efficiency with network servers and its friendly syntax makes it a great choice for developing networked applications.

In this tutorial, I will demonstrate how to deploy a demo Go application to Heroku. You ready? Let’s dig in.


To follow this tutorial, a few things are required:

  1. Basic knowledge of programming
  2. Go installed on your system (you can find an installation guide here)
  3. An account on Heroku
  4. A CircleCI account
  5. A GitHub account

With all these installed and set up, let’s begin the tutorial.

Building a simple API with Go

Let’s begin by creating a very simple mock API with two endpoints. One endpoint for the API root, /, and another endpoint, /register, that receives some user data, and echoes it back in a success response formatted in json.

We will be creating this API using Go and Gin. Gin is a standard web framework for Go similar to Express.js for Node.js or Django for Python.

In a preferred location on your system, create a folder with the name go-registration-api and navigate to the root of the folder:

mkdir go-registration-api
cd go-registration-api

Next, initialize the Go project by running the following:

go mod init go-registration-api

The go mode init command is similar to npm init in Node.js. It initializes the folder as a Go project named go-registration-api. This command also creates a go.mod file at the root of the project. This file is similar to package.json file in Node.js. It manages dependencies and many more project-level configurations.

Let’s create our project entry file. At the root of the project, create the entry file named main.go and paste in the following code:

package main

import "fmt"

func main (){
    fmt.Println("It's Aliveeee!!!")

This is a simple “Hello World” Go application where we yell “It’s Aliveeee!!!” to the screen, waking up Frankenstein’s monster.

To run our code, head over to your Terminal. At the root of the project, run the following command:

go run main.go

In the above code, we call Go’s run command, and supply it with the file we want to run. This will compile and run the code. It's Aliveeee!!! is printed on the CLI.

For convenience, we don’t want to have to run go run main.go each time we choose to run our application, so we need to create a makefile file. Create a file named makefile at the root of the project (no file extension). This file will help us proxy some of our commonly used Go CLI commands with simpler ones. Enter the following into the makefile:

  go run main.go

Note: Makefiles only work with tabs. The second line above is tabbed once.

Here, we have created a proxy dev command for go run main.go. Now we can run the following:

make dev

This will give us the same result as running go run main.go. It serves as our command for running the Go project in development mode.

Building the API

Now we can begin building our mock API. First, install the Gin framework by running the following command:

go get -u github.com/gin-gonic/gin

This downloads all the packages required for operating with Gin. A go.sum file is created at the root of the project. This file works like the package-lock.json in Node.js. It keeps track of the exact version of all the packages being installed in the project.

Once Gin is installed, replace all the code in main.go:

package main

import "github.com/gin-gonic/gin"

func main() {
  r := gin.Default()
  r.GET("/", func(c *gin.Context) {
    c.JSON(200, gin.H{
      "message": "Welcome to the Go Registration API",

  r.POST("/register", func(c *gin.Context) {
    fullname := c.PostForm("fullname")
    phone := c.PostForm("phone")
    email := c.PostForm("email")

    c.JSON(200, gin.H{
      "status":   "success",
      "message":  "User details successfully posted",
      "fullname": fullname,
      "phone":    phone,
      "email":    email,

In the code above, we start by importing the gin package. Then, in our main function, we created a new gin with the following line.

r := gin.Default()

This command returns a router that includes helpful middleware for tasks like logging and recovery. Next, we created two endpoints:

  • /: A GET endpoint that returns a json object with a message welcoming the user to the API
  • /register: A POST endpoint that receives a user’s form data, and echoes it back in a json success response

Finally, we call r.Run() to make sure that the application doesn’t exit, but keeps running.

Running the API endpoints

Time to take our mock API for a spin. Run the application by typing the following command:

make dev

This will boot up a local server to serve the application at http://localhost:8080.

Note: If the application was running while you were making the changes, shut down the app with Ctrl + C and restart it.

Using Postman to call the endpoints results in the following two screenshots.

Home endpoint test

Register endpoint test

Setting up a Heroku app for deployment

We need a hosting service to deploy our Go application; I chose Heroku for this tutorial. Set up a Heroku application by navigating to the Heroku dashboard and clicking New. Select Create new app and fill in the application name.

New App - Heroku

After creating the application successfully, you will be redirected to the application page. Remember your application name, in this case go-registration-api, as you will be needing it later on.

Find your Heroku API key, located on your Account Settings page. You can access Account Settings from the dropdown menu that appears when you click your avatar at the top right of the webpage.

Connecting the project to CircleCI

Now that we have Heroku set up, we need to automate the deployment of our Go application. Begin by pushing your project to GitHub.

Next, go to the Add Projects page on the CircleCI dashboard.

Add Project - CircleCI

Click Set Up Project.

Add Config - CircleCI

On the set-up page, click Use Existing Config to instruct CircleCI that we are adding a configuration file manually, not using the sample displayed. Next, you get a prompt to either download a configuration file for the pipeline or start building.

Build Prompt - CircleCI

Click Start Building. This build will fail because we have not set up our configuration file yet.

Next, we need to set up environment variables for the project we just added. This provides our project with authenticated access to Heroku for deployments.

Click Project Settings on the Pipelines page. Make sure your project is currently selected.

Project settings - CircleCI

On the Project Settings page, click Environment Variables on the side menu.

Environment variables - CircleCI

On the Environment Variables page, click Add Environment Variable. Add these variables:

  • HEROKU_APP_NAME: In this case, go-registration-api is the name of your Heroku application
  • HEROKU_API_KEY: Find your Heroku account API key on the Account tab

Success! You have completed set up on your CircleCI console for deployment to Heroku.

Configuring automated deployment with CircleCI orbs

Now it is time to get our Go application deployed, and make it truly “Aliveeee!!!”. First, we need to create a Procfile file at the root of the project.

Create the Procfile file (with no file extension), and add the following command to the file:

web: bin/go-registration-api

Heroku runs the built version of our Go application, located in the bin directory.

Next, create a deployment pipeline configuration file to contain our configuration script. At the root of the project, create a folder named .circleci. Create a config.yml file within that folder. Inside the config.yml file, enter the following configuration:

version: 2.1
  heroku: circleci/heroku@0.0.10
      - heroku/deploy-via-git

We can deploy our application with only seven lines of code because we are using the power of CircleCI orbs. The configuration pulls in CircleCI’s Heroku orb. This orb abstracts a lot of boilerplate Heroku CLI commands, and provides an easy-to-use API for deploying applications.

Next, we call the heroku/deploy-via-git job. This job checks out our code from the remote repository and deploys it to Heroku. It authenticates with Heroku using the environment variables we defined earlier.

Commit the changes to your project, and push to the remote repository to run the deployment script.

Build Successful - CircleCI

Click the SUCCESS label to view the details of the deployment.

Build Details - CircleCI

The status details are logged to show how Heroku detects the app as a Go application, installs dependencies, builds the project, and runs the command in our Procfile file.

Go to our application at https://go-registration-api.herokuapp.com.

App Live - Heroku

We can also test our /register endpoint on the live application using Postman.

Postman Live Test


Go is an option for developers who love the fancy features of newer languages and frameworks, but want the power and enterprise-grade features of C, Java, and C++. If you are bored or frustrated with Node.js, Python, and Ruby, why not give Go a try?

Happy coding!

Fikayo Adepoju is a LinkedIn Learning (Lynda.com) Author, Full-stack developer, technical writer, and tech content creator proficient in Web and Mobile technologies and DevOps with over 10 years experience developing scalable distributed applications. With over 40 articles written for CircleCI, Twilio, Auth0, and The New Stack blogs, and also on his personal Medium page, he loves to share his knowledge to as many developers as would benefit from it. You can also check out his video courses on Udemy.

Read more posts by Fikayo Adepoju