Upload debug symbols for Go

Install posthog-cli:

npm install -g @posthog/cli

curl --proto '=https' --tlsv1.2 -LsSf https://download.posthog.com/cli | sh
posthog-cli-update

To authenticate the CLI, call the login command. This opens your browser where you select your organization, project, and API scopes to grant:

posthog-cli login

If you are using the CLI in a CI/CD environment such as GitHub Actions, you can set environment variables to authenticate:

You can also use the --host option instead of the POSTHOG_CLI_HOST environment variable to target a different PostHog instance or region. For EU users:

posthog-cli --host https://eu.posthog.com [CMD]

Go embeds DWARF debug info in every binary by default, but the SDK and CLI need a little help depending on the platform.

On Linux, add a GNU build ID — the unique identifier PostHog uses to match stack frames to uploaded symbols. Go doesn't emit one by default:

go build -ldflags="-B gobuildid" -o my-app .

On macOS, keep the DWARF uncompressed. Binaries always carry a Mach-O UUID, so there is no build ID step, but Go compresses debug info by default and compressed DWARF can't be used for symbolication yet:

go build -ldflags="-compressdwarf=false" -o my-app .

Watch out for flags that remove what the upload needs: -ldflags="-w" or -ldflags="-s" strip DWARF entirely, and -trimpath rewrites the source paths that --include-source relies on.

Point the CLI at the directory containing your built binary:

posthog-cli symbol-sets upload --directory ./bin

The CLI scans the directory and uploads every executable that carries debug info and an identity, skipping everything else. On macOS the Go binary uploads directly — Go never produces a .dSYM bundle, and none is needed. Universal (fat) binaries upload one symbol set per architecture slice. Windows binaries are not supported yet: the SDK sends plain runtime-resolved frames there.

Run this as part of the same pipeline that produces your production binary. Each build has its own identity, so symbols must be re-uploaded for every build you deploy.

By default, only debug symbols are uploaded. To also display the source code around each frame in your stack traces, add --include-source:

posthog-cli symbol-sets upload --directory ./bin --include-source

This bundles the project source files referenced by the debug info into the upload. It increases upload size, so only enable it if you want source context in the error tracking UI. It also requires building without -trimpath, since the CLI reads sources from the paths recorded at compile time.

In CI, authenticate with environment variables instead of posthog-cli login. For GitHub Actions:

- name: Build release binary
  run: go build -ldflags="-B gobuildid" -o bin/my-app .

- name: Upload debug symbols
  run: posthog-cli symbol-sets upload --directory ./bin
  env:
    POSTHOG_CLI_API_KEY: ${{ secrets.POSTHOG_CLI_API_KEY }}
    POSTHOG_CLI_PROJECT_ID: ${{ secrets.POSTHOG_CLI_PROJECT_ID }}

Scope the credentials to the upload step only — the build itself doesn't need them.

The CLI defaults to US Cloud. If you are on EU Cloud or self-hosted, also set POSTHOG_CLI_HOST (for example https://eu.posthog.com).

If your binary is built inside a Dockerfile, run the upload in the build stage right after the build, and pass the credentials in as build secrets so they never reach the runtime image.

Capture a test exception from the same binary the symbols were uploaded for:

exception := posthog.NewDefaultException(
    time.Now(),
    "test_user",
    "TestError",
    "This is a test exception from Go",
)
client.Enqueue(exception)
client.Close()

Run the binary, then check the error tracking issues view: the stack trace should resolve against the uploaded symbols, including source context if you uploaded with --include-source. A rebuild changes the binary's identity, so if you rebuild, upload again before testing.