Golang Project GitHub Actions Unit Test Workflow Configuration Guide

In the development of Golang projects, automated testing is the infrastructure for ensuring code quality. GitHub Actions, as a natively integrated CI/CD tool, can help developers quickly establish automated testing workflows for code pushes and pull requests.

This article will systematically introduce how to configure GitHub Actions workflows for Golang library projects to achieve automatic triggering and execution of unit tests.

Applicable scenarios

• Continuous Integration for Open Source Golang Library Projects

• Code quality control for team-internal private repositories

• Ensuring regression testing during multi-branch parallel development

After configuration is complete, every code push or pull request will automatically trigger compilation, static checks, and unit tests, and the test results will be clearly displayed on the GitHub Actions page.

Step 1: Create a workflow configuration file

Create the GitHub Actions workflow directory and configuration file in the project root directory:

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

Step 2: Write the workflow configuration

Edit .github/workflows/test.yaml, add the following content:

name: test

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

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      GENERAL_RUNNING_MODE: workflow
      ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          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 private repository access token

If the project depends on a private GitHub repository, you need to configure a Personal Access Token for authentication:

• Go to the GitHub repository page and click Settings → Secrets and variables→Actions

• at Repository secrets Click in the tab New repository secret

• Name entry ACCESS_TOKEN, the value is with repo GitHub Personal Access Token with permissions

If the project has no private dependencies, you can delete it from the configuration file.ACCESS_TOKEN Related environment variables and Git configuration steps.

Workflow Configuration Parsing

Configuration item	Description
on.push.branches	Branch push rules that trigger workflows, covering the main branch and various development branches.
on.pull_request.branches	Triggered when the Pull Request target branch is master
actions/setup-go@v4	Automatically install the Go environment, version from go.mod hit the target go Instruction read
git config	Use an Access Token instead of the default HTTPS authentication method to support pulling private repositories.
go vet	Run the official Go language static code analysis tool
go test -race -count=1	Enable race detection and disable test caching to ensure reliable results on every run.

Verify whether the workflow takes effect

• Commit and push the configuration file to the GitHub repository.

• Click on the repository page Actions tab

• Select the corresponding workflow run record to view real-time logs and test results.

If any step fails, the workflow will exit with a non-zero status code and be marked as failed in the Actions interface, making it easy for developers to quickly identify the problem.

Common Questions and Optimization Suggestions

1. Failed to pull private dependencies

Check ACCESS_TOKEN whether it is correctly configured, and the token has repo Scope. If multiple private repositories belong to the same organization, you can use GOPRIVATE Unified environment variable configuration:

env:
  GOPRIVATE: github.com/your-org

2. Test execution takes a long time.

Can be introduced actions/cache Cache Go modules to reduce dependency download time:

- uses: actions/cache@v3
  with:
    path: ~/go/pkg/mod
    key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }}

3. Multi-Go version compatibility testing

Run tests across multiple Go versions using a matrix strategy:

strategy:
  matrix:
    go-version: ['1.20', '1.21', '1.22']

Summary

With the above configuration, a standard Golang unit test CI pipeline is now fully deployed. This workflow can cover code changes in the main branch and various development branches, providing code quality assurance at three levels: compilation, static analysis, and unit testing. Whether for open-source projects or internal team repositories, this configuration offers good generality and maintainability.

Add this workflow to your Golang repository now, making continuous integration a reliable part of your development process.

Further reading:GitHub Actions official documentation - Building and testing Go