docs: Improve analyzer documentation around why a specific template job is running
Problem to solve
It's not always clear why an analyzer job is running in a pipeline. We should improve our documentation around this.
Example configuration for semgrep:
- template configuration: https://gitlab.com/gitlab-org/gitlab/-/blob/d57f07b5e02dc00fe1d7a9b89bdee8a38621c739/lib/gitlab/ci/templates/Jobs/SAST.gitlab-ci.yml#L224
-
semgrep/plugin.go
logic: https://gitlab.com/gitlab-org/security-products/analyzers/semgrep/-/blob/77569f6e25763fa44c6587ac7ed38b744f04dbc3/plugin/plugin.go#L25
Proposal
There are essentially two stages to job evaluation:
- CI templates
rules
configuration - Analyzer's
plugin.go
architecture for evaluating a match.
The reason there are two levels is because the first should filter our unnecessary executions to save on CI minutes. The latter is a more sophisticated check to evaluate project efficacy.
We should also document the situations where this may vary if the templates rules are overridden.
Who can address the issue
groupstatic analysis, groupcomposition analysis, groupdynamic analysis