Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(go): improve docs on troubleshooting default go detection strategy #740

Closed
wants to merge 4 commits into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 18 additions & 9 deletions docs/detectors/go.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,29 +2,38 @@

## Requirements

Go detection depends on the following to successfully run:
Go detection runs when one of the following files is found in the project:

- `go.mod` or `go.sum` files
- `go.mod` or `go.sum`

## Default Detection strategy

Go detection depends on the following to successfully run:
Default Go detection depends on the following to successfully run:

- Go v1.11+.

Full dependency graph generation is supported if Go v1.11+ is present on the build agent.
If no Go v1.11+ is present, fallback detection strategy is performed.

Go detection is performed by parsing output from executing [go list -m -json all](1). To generate the graph, the command [go mod graph](2) is executed, this only adds edges between the components that were already registered by `go list`.
Go detection is performed by parsing output from executing [go list -mod=readonly -m -json all](1). To generate the graph, the command [go mod graph](2) is executed. This only adds edges between the components that were already registered by `go list`.

## Fallback Detection strategy
Go detection is performed by parsing any `go.mod` or `go.sum` found under the scan directory.

Only root dependency information is generated instead of full graph.
I.e. tags the top level component or explicit dependency a given transitive dependency was brought by.
Given a dependency tree A -> B -> C, C's root dependency is A.
Only root dependency information is generated in the fallback detection strategy. The full graph is not detected. Given a dependency tree `A->B->C`, only `A`, `C`'s root dependency, is detected.

**To force fallback detection strategy, create set environment variable `DisableGoCliScan=true`.**
To force fallback detection strategy, set the following environment variable: `DisableGoCliScan=true`

## Troubleshooting failures to run the default detection strategy
The fallback detection strategy is known to overreport by nature of parsing `go.sum` files. To ensure the newer, more accurate default detection strategy runs successfully, it is encouraged to do the following:

1. Ensure that Go v1.11+ is installed on the build agent.

1. Resolve `go list` errors. Errors are logged in the Component Detection build task output and begin with `#[error]Go CLI command "go list -m -json all" failed with error:`. These errors are typically caused by version resolution problems or incorrectly formatted `go.mod` files.

1. Ensure that `DisableGoCliScan` is **not** set to `true`. The variable should not be set or should be set to `false`.

1. Fetch Go modules before the Component Detection build task runs. If modules are not fetched, `go list` will pull the modules and may negatively impact performance.

## Known limitations
- If the default strategy is used and go modules are not present in the system before the detector is executed, the go cli will fetch all modules to generate the dependency graph. This will incur additional detector time execution.
Expand All @@ -40,7 +49,7 @@ Executing [go mod tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via

## Environment Variables

If the environment variable `DisableGoCliScan` is set to `true`, the Go detector parses `go.mod` and `go.sum` to discover dependencies. otherwise, it executes default strategy.
If the environment variable `DisableGoCliScan` is set to `true`, the Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy).

[1]: https://go.dev/ref/mod#go-list-m
[2]: https://go.dev/ref/mod#go-mod-graph