---
title: "Language guide: Go"
description: "Set up a Go project with CircleCI. Follow a configuration walkthrough to create a basic config.yml file that builds, tests, and deploys your project."
platform: "Cloud, Server"
doc_version: "Server"
last_updated: "2026-10-20"
---

> For current CircleCI product defaults, deprecated patterns, and Cloud/Server differences, see [AGENTS.md](https://circleci.com/docs/AGENTS.md).
>
> For the complete documentation index and site structure, see [llms.txt](https://circleci.com/docs/llms.txt).

# Language guide: Go

This quickstart guide covers integrating a Go project with CircleCI. This guide is designed to help you create a basic CircleCI configuration file to build, test, and deploy your Go project. After completing this quickstart, you can edit and optimize the config to fit the requirements of your project.

## Prerequisites

*   An account on your CircleCI Server instance.
    
*   A Go project located in a GitHub repository.
    

## Configuration walkthrough

Every CircleCI project requires a configuration file called [`.circleci/config.yml`](https://circleci.com/docs/reference/configuration-reference/). Follow the steps below to create a working `config.yml` file.

### 1\. Specify a version

Every CircleCI config.yml starts with the version key. This key is used to issue warnings about breaking changes.

```yaml
version: 2.1
```

`2.1` is the latest CircleCI version, and it ensures you have access to all our latest features and improvements.

### 2\. Use the Go orb

The Go [orb](https://circleci.com/developer/orbs/orb/circleci/go) contains a set of prepackaged CircleCI configurations you can use to perform common CircleCI tasks for the Go programming language. It supports Linux x86\_64. Learn more about [Orbs](https://circleci.com/docs/orbs/use/orb-intro/).

To add the orb to your config, insert:

```yaml
orbs:
  go: circleci/go@3.0.2
```

When using an orb, check the [Orb Registry](https://circleci.com/developer/orbs) to confirm you are using the most recent version. Alternatively, use the version that best fits your specific project.

### 3\. Create jobs

Jobs are the building blocks of your config. Jobs are collections of steps, which run commands/scripts as required. All of the steps in the job are executed in a single unit, either within a fresh container or virtual machine. Learn more about jobs on the [Jobs and Steps](https://circleci.com/docs/guides/server/orchestrate/jobs-steps/) page.

A common ask from developers who are getting started with CircleCI is to perform three basic tasks: `build`, `test` and `deploy`. This section guides you through each of the config changes needed. Because we are using the official Go orb, we can use commands that are built into the orb to keep our config simple and succinct.

#### a. Build and test the app

For this step, we use commands that come preconfigured in the Go [orb](https://circleci.com/developer/orbs/orb/circleci/go). The `go/mod-download` command downloads Go modules and caches them automatically. Tests are run using the `go/test` command.

```yaml
jobs:
  build_and_test: # this can be any name you choose
    executor:
      name: go/default # Use the default executor from the orb
      tag: '1.22' # Specify a version tag
    steps:
      - checkout # checkout source code
      - go/mod-download # Download and cache Go modules
      - go/test: # Runs 'go test ./...' but includes extensive parameterization for finer tuning.
          covermode: atomic
          failfast: true
          race: true
      - persist_to_workspace:
          root: ~/project
          paths: .
```

#### b. Deploy the app

In this quickstart guide, we will deploy to [Heroku](https://www.heroku.com/). We can do this using the official Heroku orb by adding a new line into our orb section. The Heroku orb contains a set of prepackaged CircleCI configurations you can use to deploy applications to Heroku. Learn more about the [Heroku orb](https://circleci.com/developer/orbs/orb/circleci/heroku).

```yaml
orbs:
  go: circleci/go@3.0.2
  heroku: circleci/heroku@2.0.0
```

We then need to add a job to our list to take care of the deploy step:

```yaml
jobs:
  # ...previous job(s)...
  deploy: # this can be any name you choose
    executor: heroku/default # use the default executor defined within the orb
    steps:
      - attach_workspace:
          at: ~/project
      - heroku/deploy-via-git:
          force: true # force push when pushing to the heroku remote, see: https://devcenter.heroku.com/articles/git
```

Environment variables containing the necessary secrets such as `HEROKU_API_KEY` and `HEROKU_APP_NAME` can be set up in the CircleCI web app. Learn more about [Environment Variables](https://circleci.com/docs/guides/server/security/set-environment-variable/#set-an-environment-variable-in-a-project).

### 4\. Create a workflow

A workflow is a set of rules for defining a collection of jobs and their run order. Workflows support complex job orchestration using a set of configuration keys to help you resolve failures sooner. Inside the workflow, you define the jobs you want to run. CircleCI will run this workflow on every commit. Learn more about [Workflow Configuration](https://circleci.com/docs/reference/configuration-reference/#workflows).

```yaml
workflows:
  build_test_deploy: # this can be any name you choose
```

### 5\. Add jobs to the workflow

Now that we have our workflow, `build_test_deploy`, we can use it to orchestrate the running of our `build_and_test` and `deploy` jobs. Refer to the [Using Workflows to Orchestrate Jobs](https://circleci.com/docs/guides/server/orchestrate/workflows/) page for more details about orchestrating jobs with concurrent, sequential, and manual approval workflows.

```yaml
workflows:
  build_test_deploy:
    jobs:
      - build_and_test
      - deploy:
          requires:
            - build_and_test # only deploy if the build_and_test job has completed
          filters: pipeline.git.branch == "main" # only run the deploy job on the main branch
```

### 6\. Conclusion

You just set up a Go app to build on CircleCI and deploy to Heroku. Check out your project’s [Pipeline Page](https://circleci.com/docs/guides/server/orchestrate/pipelines/) to see how this looks when building on CircleCI.

**Deploy options?** For alternative deployment targets, search the [orb registry](https://circleci.com/developer/orbs), where you will find integrations such as [Kubernetes](https://circleci.com/developer/orbs/orb/circleci/kubernetes), [AWS ECS](https://circleci.com/developer/orbs/orb/circleci/aws-ecs), [GCP GKE](https://circleci.com/developer/orbs/orb/circleci/gcp-gke), and more.

## Full configuration file

```yaml
version: 2.1
orbs:
  go: circleci/go@3.0.2
  heroku: circleci/heroku@2.0.0

jobs:
  build_and_test: # this can be any name you choose
    executor:
      name: go/default # Use the default executor from the orb
      tag: '1.22' # Specify a version tag
    steps:
      - checkout # checkout source code
      - go/mod-download # Download and cache Go modules
      - go/test: # Runs 'go test ./...' but includes extensive parameterization for finer tuning.
          covermode: atomic
          failfast: true
          race: true
      - persist_to_workspace:
          root: ~/project
          paths: .

  deploy: # this can be any name you choose
    executor: heroku/default
    steps:
      - attach_workspace:
          at: ~/project
      - heroku/deploy-via-git:
          force: true # force push when pushing to the heroku remote, see: https://devcenter.heroku.com/articles/git

workflows:
  build_test_deploy:
    jobs:
      - build_and_test
      - deploy:
          requires:
            - build_and_test # only deploy if the build_and_test job has completed
          filters: pipeline.git.branch == "main" # only run the deploy job on the main branch
```

## See also

*   [Continuous integration for Go applications](https://circleci.com/blog/continuous-integration-for-go-applications/)
    
*   [Parallelism and Test Splitting](https://circleci.com/docs/guides/server/optimize/parallelism-faster-jobs/)