gosocialcheck checks whether a Go module is already adopted by a trustworthy project.

List of trusted projects:

• CNCF Graduated (Kubernetes, containerd, etc.)

go install github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck@latest

# Set the token if facing the GitHub API rate limit (see below)
export GITHUB_TOKEN=...

gosocialcheck update

gosocialcheck run ./...

This command checks whether the dependencies of the current module (./...) are used by trusted projects. This command does not check whether the the current module itself is used by trusted projects.

Example output:

/Users/suda/gopath/src/github.com/AkihiroSuda/gosocialcheck/pkg/analyzer/analyzer.go:18:2:
import 'golang.org/x/tools/go/analysis': module 'golang.org/x/tools@v0.33.0' does not seem adopted by a trusted project (negligible if you trust the module)
/Users/suda/gopath/src/github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck/commands/run/run.go:5:2:
import 'golang.org/x/tools/go/analysis/singlechecker': module 'golang.org/x/tools@v0.33.0' does not seem adopted by a trusted project (negligible if you trust the module)
/Users/suda/gopath/src/github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck/main.go:8:2:
import 'github.com/lmittmann/tint': module 'github.com/lmittmann/tint@v1.0.7' does not seem adopted by a trusted project (negligible if you trust the module)

Pass --gha to emit findings as workflow commands so they show up as annotations (up to 10) on the workflow run and any associated PR. In this mode the command always exits 0.

To stay within GitHub's annotation limits, --gha caps the number of emitted annotations and reports findings whose go.sum line changed in the PR first. On a pull_request event it fetches the base branch (GITHUB_BASE_REF) on demand to detect those lines, so the default shallow checkout works as-is:

- uses: actions/checkout@v4
- run: go install github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck@latest
- run: gosocialcheck run --gha ./...

Use //gosocialcheck:trusted directives in go.mod to silence alerts for trustworthy modules.

e.g.,

//gosocialcheck:trusted
require (
	golang.org/x/sync v0.19.0
)

or

require (
	golang.org/x/sync v0.19.0 //gosocialcheck:trusted
)

Note: The directive ignores the module version.

gosocialcheck keeps two cache flavors under $XDG_CACHE_HOME/gosocialcheck (~/Library/Caches/gosocialcheck on macOS):

• _remote: a shallow clone of AkihiroSuda/gosocialcheck-cache, preprocessed and ready to use.
• _local: rebuilt locally from the CNCF project list and the GitHub API (gosocialcheck update --cache-mode=local).

The --cache-mode flag (or $GOSOCIALCHECK_CACHE_MODE) selects which one is used:

• auto (default): for reads, picks whichever has the more recent ModTime. For update, fetches the remote.
• remote: use the preprocessed remote cache.
• local: rebuild and use the local cache.

gosocialcheck run populates the cache automatically on the first run.

Run gosocialcheck info (or gosocialcheck info --json) to inspect the current cache state.

gosocialcheck uses the GitHub API for the following operations:

• Fetch git tags, via api.github.com.
• Fetch go.mod and go.sum, via https://raw.githubusercontent.com.

These API calls often fails unless the API token is set.

To mitigate the API rate limit, set the token as follows:

1. Open https://github.com/settings/tokens/.
2. Click Generate new token.
3. Generate a token with the following configuration:

• Token name: (arbitrary name, e.g., gosocialcheck)
• Expiration: (arbitrary lifetime, but 365 days at most)
• Repository access: Public repositories
• Account permissions: No access for all.

4. Set the token as $GITHUB_TOKEN.

export GITHUB_TOKEN=...