Use the Go multimodules action

The go-multimodules composite action orchestrates independently reusable actions for discovery, per-module commands, and tests/coverage. They read go.work when present; otherwise they find go.mod files directly. If a workspace omits a module, discovery fails rather than silently skipping it. All actions use Bash and standard Go tooling. Some specific actions may rely on additional tools and dependencies though.

Call it from this repository

This repository's workflows use:

- uses: $/actions/go-multimodules
  with:
    task: build

$/actions/... resolves an action from the repository containing the workflow, at the same revision as that workflow. This keeps the workflow and action together when a reusable workflow is called by another repository. It also lets a pull request exercise its own changes to the action. The action lives at actions/go-multimodules/action.yml.

The top-level action composes detect-go-modules, run-go-modules (for generation and lint), and test-go-modules (for JUnit and merged coverage). Use it for the complete pipeline, or call any of its components on their own.

Call it from another repository

Use a repository-qualified reference in the other repository's workflow. Pin it to a full commit SHA or a version number available in ARM-software/golang-utils:

name: Go modules
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      checks: write
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-go@v7
        with:
          go-version: '1.26.1' # Choose the version required by your modules.
          cache-dependency-path: '**/go.sum'
      - uses: ARM-software/golang-utils/actions/sync-go-workspace@<full-commit-sha>
        if: ${{ hashFiles('go.work') != '' }}
      - uses: golangci/golangci-lint-action@v9
        with:
          version: latest
          install-only: true
      - uses: ARM-software/golang-utils/actions/setup-gotestsum@<full-commit-sha>
        with:
          version: v1.13.0
      - uses: ARM-software/golang-utils/actions/go-multimodules@<full-commit-sha>
        with:
          task: verify
          build-tags: integration
          artifact-prefix: '${{ github.job }}-'

Replace <full-commit-sha> with a real commit SHA or a version number from this repository. The $/actions/... reference is for actions in the workflow's repository; in the example above it would point at the calling repository, so the repository-qualified reference is required instead. artifact-prefix is optional; it helps prevent name collisions if several action invocations upload reports in the same run.

Choose an individual action

Action Standalone purpose Useful inputs and outputs
detect-go-modules Verify that no module is omitted. Outputs modules (newline-delimited) and modules-json for a matrix.
sync-go-workspace Run go work sync at the checked-out repository root. No inputs; requires Go and go.work.
setup-gotestsum Install the gotestsum test runner and put it on PATH. version defaults to v1.13.0.
run-go-modules Run one task across all modules. Set task to generate, lint, build, download, or analyze; optionally supply modules, results-file, skip-results-file, and build-tags.
test-go-modules Test modules with gotestsum, merge coverage and publish reports. Optionally supply modules, generation-results, lint-results, artifact-prefix, and build-tags; outputs combined-coverage.
go-multimodules Compose discovery, generation, lint and testing in one call. Set task (default verify) and optionally build-tags; outputs modules-json.

The individual actions can be used independently. If modules is omitted, run-go-modules and test-go-modules call the discovery action themselves. In this repository use $/actions/<name> to call each action; from another repository use ARM-software/golang-utils/actions/<name>@<full-commit-sha>.

For example, to choose the stages separately in another repository, add the following steps after checkout, Go setup, optional workspace sync, and the setup-gotestsum and golangci-lint-action installation steps (as in the complete example above):

- id: modules
  uses: ARM-software/golang-utils/actions/detect-go-modules@<full-commit-sha>
- id: generate
  continue-on-error: true
  uses: ARM-software/golang-utils/actions/run-go-modules@<full-commit-sha>
  with:
    task: generate
    build-tags: integration
    modules: ${{ steps.modules.outputs.modules }}
    results-file: artifacts/generate.tsv
- id: lint
  if: ${{ always() }}
  continue-on-error: true
  uses: ARM-software/golang-utils/actions/run-go-modules@<full-commit-sha>
  with:
    task: lint
    build-tags: integration
    modules: ${{ steps.modules.outputs.modules }}
    results-file: artifacts/lint.tsv
    skip-results-file: artifacts/generate.tsv
- id: test
  if: ${{ always() }}
  uses: ARM-software/golang-utils/actions/test-go-modules@<full-commit-sha>
  with:
    build-tags: integration
    modules: ${{ steps.modules.outputs.modules }}
    generation-results: artifacts/generate.tsv
    lint-results: artifacts/lint.tsv
    artifact-prefix: '${{ github.job }}-'

The TSV results allow later stages to report generation and lint failures without concealing test results. Use the same pinned SHA/version for every component so their interfaces stay in sync. Build, analysis, generation, lint, and tests include the integration build tag by default; download and discovery do not compile tagged packages. Override build-tags if the calling project needs additional tags.

Tasks and reports

Top-level task Result
list List the modules selected from go.work or go.mod files.
download Run go mod download for each module with GOWORK=off.
build Build every module.
analyze Compile tests in every module without running test cases (for CodeQL).
generate Run go generate in every module.
lint Run golangci-lint in every module.
verify (default) Generate, lint and test each module with gotestsum; collect coverage and reports.

verify calls the granular generation, lint and test actions in order. The test action uploads one JUnit XML file and one coverage profile per module, plus a project-wide combined.out coverage profile. Test results are rendered in the workflow summary and, for same-repository pull requests, PR comments via EnricoMi/publish-unit-test-result-action. The JUnit artifact keeps the raw per-module XML plus EnricoMi's combined JSON report, while the local summary keeps every module's generate, lint and test status, per-module coverage, and links to the uploaded reports. Artifact uploads and summaries also run when verification fails, so available failure reports remain accessible.

Set up Go before using any task. For verify or lint, install golangci-lint; for verify, also install gotestsum. GitHub-hosted runners provide the Bash and standard Unix tools used by the action.