Troubleshooting¶

Common issues and solutions for Go Gamma Actions.

Build Issues¶

"go.mod not found"¶

Cause: Wrong working-directory or missing go.mod.

Solution:

with:
  working-directory: './path/to/module'

"module requires Go X.XX"¶

Cause: Go version mismatch.

Solution:

with:
  go-version: '1.24'  # Match your go.mod

Or use automatic detection:

with:
  go-version-file: 'go.mod'

Build fails on Windows¶

Cause: Path or CGO issues.

Solutions:

Check path separators in code
Disable CGO (default in builds):
```
// +build !cgo
```

Test Issues¶

Race detector timeouts¶

Cause: Race detection adds overhead.

Solutions:

Increase timeout:
```
with:
  test-flags: '-v -timeout=30m'
```
Disable for slow tests:
```
with:
  race-detection: false
```

Coverage upload fails¶

Cause: Missing or invalid Codecov token.

Solutions:

Verify secret exists in repository settings

Check token is correct:

secrets:
  CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

For public repos, try without token

Lint Issues¶

Too many issues¶

Cause: Strict defaults on legacy code.

Solutions:

Focus on new issues:
```
with:
  only-new-issues: true
```
Create custom config:
```
with:
  config-path: '.golangci.yml'
```

"could not load config"¶

Cause: Invalid golangci-lint configuration.

Solution:

Test config locally:

golangci-lint run --config .golangci.yml

Linter timeout¶

Cause: Large codebase or complex analysis.

Solution:

Configure in .golangci.yml:

run:
  timeout: 10m

Security Issues¶

SARIF upload fails¶

Cause: Missing permissions or GitHub Advanced Security.

Solutions:

Add permissions:
```
permissions:
  security-events: write
```
For private repos, enable GitHub Advanced Security
Disable SARIF:
```
with:
  upload-sarif: false
```

govulncheck finds false positives¶

Cause: Vulnerability in unused code path.

Note: govulncheck performs reachability analysis. If it reports a vulnerability, the vulnerable code path is actually used.

Solution:

Update the dependency:

go get -u vulnerable/module

Permission Issues¶

"Resource not accessible"¶

Cause: Insufficient workflow permissions.

Solution:

permissions:
  contents: read
  security-events: write

jobs:
  ci:
    uses: go-gamma/actions/.github/workflows/ci.yml@v1
    permissions:
      contents: read
      security-events: write

Release creation fails¶

Cause: Missing write permissions.

Solution:

permissions:
  contents: write

Workflow Issues¶

Job skipped unexpectedly¶

Cause: Dependency failure or condition not met.

Debug:

Check dependent job status
Review job conditions
Verify skip-* inputs

Workflow not triggered¶

Cause: Branch/path filters.

Solution:

Check on: configuration:

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

Getting Help¶

Debug Information¶

Enable debug logging:

Add secret ACTIONS_STEP_DEBUG = true
Re-run workflow

Report Issues¶

File issues at: github.com/go-gamma/actions/issues

Include:

Workflow file (sanitized)
Error messages
Go version
Repository visibility (public/private)