Golang Project CI Primer: 3 Steps to Configure GitHub Actions Automated Unit Testing

Automated testing is the first line of defense for ensuring code quality, and GitHub Actions makes it all simple and efficient.

In Golang project development, manually running tests after every code change is both tedious and easy to miss. GitHub Actions provides powerful CI/CD capabilities, allowing us to easily automate running unit tests when code is pushed or a merge request is made. This article will walk you through how to configure it quickly.

Why is automated testing needed?

• Identify problems in a timely manner: Automatically run tests on every code commit to catch regression issues immediately.

• Ensure code quality: Enforcement go vet Static analysis to avoid potential errors

• Improve collaboration efficiency Team members do not need to worry about test environment configuration; execution is unified in the cloud.

• Save time: Automated processes free up developers’ time spent on manual testing

Preparatory work

Before you begin, please make sure:

• Your project is already hosted on GitHub.

• The project root directory contains go.mod Files (Go Module project)

• If you have private dependency repositories, you need to prepare a GitHub Personal Access Token with read permission.

Step 1: Create the test workflow configuration file

In the project root directory, create a workflow configuration file:

mkdir -p .github/workflows && touch .github/workflows/test.yaml

Step 2: Write the workflow configuration

Edit .github/workflows/test.yaml File, contents as follows:

# This workflow will build a golang project
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go

name: test

on:
  push:
    branches: [ "master", "feature/*", "refactor/*", "perf/*" ]
  pull_request:
    branches: [ "master" ]

jobs:
  build:
    runs-on: ubuntu-latest
    # Set environment variables
    env:
      # Load the configuration file by accessing the runtime mode environment variable.
      GENERAL_RUNNING_MODE: workflow
      # If an organization is entirely private, you don’t need to list each repository separately; you only need to specify the organization.
      # GOPRIVATE: github.com/go-discovery,github.com/go-microservice
      ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          # Specify the Go version number (uncomment the following line to pin the version)
          # go-version: '1.22.3'
          # Recommended: Automatically read the Go version from go.mod
          go-version-file: 'go.mod'

      - name: Configure Git with access token
        run: git config --global url.https://[email protected]/.insteadOf https://github.com/

      - name: Build
        run: go build -v ./...

      - name: Static code analysis
        run: go vet ./...

      - name: Test
        run: go test -race -count=1 -v ./...

Step 3: Configure the repository access token

If your project depends on a private repository, you need to configure an access token:

• Visit your GitHub project repository

• Enter Settings→Secrets and variables→Actions

• At Repository secrets In the tab, click New repository secret

• Create one named ACCESS_TOKEN key, with the value being your GitHub Personal Access Token

Tip

If there are no private dependencies, you can delete the configuration regarding ACCESS_TOKEN the part, simplified to the standard configuration for public repositories.

Workflow Execution Process

After you complete the configuration and push the code, GitHub Actions will automatically execute the following process:

Trigger condition description

The workflow will be triggered in the following situations:

• Push event: Push to master、feature/*,refactor/*,perf/* branch

• Pull Request event: toward master Create PR from branch

You can adjust the branch name and trigger conditions according to the actual project situation.

Detailed Explanation of Test Commands

go test -race -count=1 -v ./...

• -race: Enable race detection and found data race issues

• -count=1: Disable test caching to ensure it reruns every time

• -v Output detailed logs to facilitate troubleshooting.

• ./...:Test all subpackages

Frequently Asked Questions

1. How do I pin the Go version?

comment out go-version-file Uncomment go-version And simply specify the version number.

2. What should I do if pulling private dependencies fails?

Check the following points:

• Whether ACCESS_TOKEN is correctly configured

• Does the token have repo or read:packages Permissions

• Is GOPRIVATE set correctly?

3. How to skip tests in certain directories?

can be at go test Exclude specific packages in the command, for example:

go test -race -count=1 -v $(go list ./... | grep -v /vendor/)

4. What should I do if the workflow takes too long to run?

You may consider:

• Use actions/cache Cache Go modules

• Use a matrix strategy to test multiple Go versions in parallel

• Only test packages affected by changes (advanced usage)

Conclusion

With the above three configuration steps, your Golang project gains complete automated testing capabilities. Whenever the code changes, GitHub Actions automatically runs tests to ensure code quality. This is a configuration with an extremely high return on investment and is worth adopting for every Go project.

Once configuration is complete, you can in the GitHub repository's Actions View the workflow's running status and history in the tab.

Further reading:

• GitHub Actions Official Documentation

• Go testing best practices

• actions/setup-go Usage Guide