Build and package a (reproducible) Go binary.

• Define the build.
• Assert that it is reproducible (optionally).
• Use the resultant artifacts in your workflow.

This is intended for internal HashiCorp use only; Internal folks please refer to RFC ENGSRV-084 for more details.

• Features
• Local Usage
• Usage in GHA
  • Examples
  • Inputs
  • Build Instructions
  • Ensuring Reproducibility
• Development

• Results are zipped using standard HashiCorp naming conventions.
• You can include additional files in the zip like licenses etc.
• Convention over configuration means minimal config required.
• Reproducibility is checked at build time.
• Fast feedback if accidental nondeterminism is introduced.

The core functionality of this action is contained in a Go CLI, which you can also install and use locally. See the CLI docs for more.

This Action can run on both Ubuntu and macOS runners.

This example shows building a single linux/amd64 binary.

See this simple example workflow running here.

name: Minimal Example (main)
on: push
jobs:
  example:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build
        uses: hashicorp/actions-go-build@main
        with:
          go_version: 1.24
          os: linux
          arch: amd64
          work_dir: testdata/example-app
          debug: true
          instructions: |
            go build -o "$BIN_PATH" -trimpath -buildvcs=false

This example shows usage of the action inside a matrix configured to produce binaries for different platforms. It also injects the version, revision, and revision time into the binary via -ldflags, uses the netcgo tag for darwin, and disables CGO for linux and windows builds.

See this matrix example workflow running here.

name: Matrix Example (main)
on: push
jobs:
  example:
    runs-on: ${{ matrix.runner }}
    strategy:
      matrix:
        include:
          - { runner: macos-latest,  os: darwin,  arch: amd64, tags: netcgo        }
          - { runner: macos-latest,  os: darwin,  arch: arm64, tags: netcgo        }
          - { runner: ubuntu-latest, os: linux,   arch: amd64, env:  CGO_ENABLED=0 }
          - { runner: ubuntu-latest, os: linux,   arch: amd64, env:  CGO_ENABLED=0 }
          - { runner: ubuntu-latest, os: windows, arch: amd64, env:  CGO_ENABLED=0 }
    steps:
      - uses: actions/checkout@v3
      - name: Build
        uses: hashicorp/actions-go-build@main
        with:
          product_name: example-app
          product_version: 1.2.3
          go_version: 1.24
          os: ${{ matrix.os }}
          arch: ${{ matrix.arch }}
          instructions: |-
            cd ./testdata/example-app && \
            ${{ matrix.env }} \
              go build \
                -o "$BIN_PATH" \
                -trimpath \
                -buildvcs=false \
                -tags="${{ matrix.tags }}" \
                -ldflags "
                  -X 'main.Version=$PRODUCT_VERSION'
                  -X 'main.Revision=$PRODUCT_REVISION'
                  -X 'main.RevisionTime=$PRODUCT_REVISION_TIME'
                "

The instructions input is a bash script that builds the product binary. It should be kept as simple as possible. Typically this will be a simple go build invocation, but it could hit a make target, or call another script. See Example Build Instructions below for examples of valid instructions.

The instructions must use the environment variable $BIN_PATH because the minimal thing they can do is to write the compiled binary to $BIN_PATH.

In order to add other files like licenses etc to the zip file, you need to write them into $TARGET_DIR in your build instructions.

When the instructions are executed, there are a set of environment variables already exported that you can make use of (see Environment Variables below).

The reproducible input has three options:

• assert (the default) means perform a verification build and fail if it's not identical to the primary build.
• report means perform a verification build, log the results, but do not fail.
• nope means do not perform a verification build at all.

See Ensuring Reproducibility, below for tips on making your build reproducible.

The examples below all illustrate valid build instructions using go build flags that give the build some chance at being reproducible.

Simplest Go 1.17 invocation. (Uses -trimpath to aid with reproducibility.)

instructions: go build -o "$BIN_PATH" -trimpath

Simplest Go 1.18+ invocation. (Additionally uses -buildvcs=false to aid with reproducibility.)

instructions: go build -o "$BIN_PATH" -trimpath -buildvcs=false

More complex build, including copying a license file into the zip and cding into a subdirectory to perform the go build.

instructions: |
	cp LICENSE "$TARGET_DIR/"
	cd sub/directory
	go build -o "$BIN_PATH" -trimpath -buildvcs=false

An example using make:

instructions: make build

With this Makefile:

build:
	go build -o "$BIN_PATH" -trimpath -buildvcs=false

See also the example workflow above, which injects info into the binary using -ldflags.

If you are aiming to create a reproducible build, you need to at a minimum ensure that your build is independent from the time it is run, and from the path that the module is at on the filesystem.

Embedding the actual 'build time' into your binary will ensure that it isn't reproducible, because this time will be different for each build. Instead, you can use the PRODUCT_REVISION_TIME which is the time of the latest commit, which will be the same for each build of that commit.

By default go build embeds the absolute path to the source files inside the binaries for use in stack traces and debugging. However, this reduces reproducibility because that path is likely to be different for different builds.

Use the -trimpath flag to remove the portion of the path that is dependent on the absolute module path to aid with reproducibility.

Go 1.18+ embeds information about the current checkout directory of your code, including modified and new files. In some cases this interferes with reproducibility. You can turn this off using the -buildvcs=false flag.

Development docs have moved to docs/development.md.

The core functionality of this action is contained in a Go CLI, which can also be installed and run locally. See the CLI docs for instructions on installing and using the CLI.