Refactor documentation of the customization of the analyzers sections
It seems that the sections Customizing the X settings
and Overriding the X settings
need some serious refactoring.
- https://docs.gitlab.com/ee/user/application_security/container_scanning/#configuration
- https://docs.gitlab.com/ee/user/application_security/dependency_scanning/#configuration
- https://docs.gitlab.com/ee/user/application_security/sast/#configuration
- https://docs.gitlab.com/ee/user/application_security/dast/#configuration
Especially the customizing section, it includes some info that is incorrect !20449 (comment 302226212).
From the discussion:
Adam:
I also don't really see the point of the Customizing the Container Scanning settings, since the behaviour of setting a global variable which might not work is really confusing and I think for most use cases, a customer would actually want to follow the directions provided by the Overriding the Container Scanning template.
I think we should either remove the
Customizing the X settings
section from all the security documentation, or make sure to document the non-obvious behaviour of how global variables won't necessarily always override the variables at the template level, and explain under which situations you would want to use a global variable.
Fabien:
For what it's worth, I prefer specific sections like
Vulnerability Whitelisting
over generic ones likeCustomizing the Container Scanning settings
. To me this user documentation is all about settings anyways.I think we should either remove the
Customizing the X settings
section from all the security documentation, or make sure to document the non-obvious behaviour of how global variables won't necessarily always override the variables at the template level, and explain under which situations you would want to use a global variable.@adamcohen I totally agree. My personal opinion is that we should get rid of these sections. Because again, these user docs are about customizing/setting up the analyzers, so
Customizing XYZ
seems totally redundant to me.
Axil:
My personal opinion is that we should get rid of these sections. Because again, these user docs are about customizing/setting up the analyzers, so
Customizing XYZ
seems totally redundant to me.We still need a place to have the example
.gitlab-ci.yml
file. In some cases, we just list the available variables in a table without an example. So, if that section was to be removed, we'd need to add an example to each section with a variable.I'm not opposed to this, I'm just stating what needs to be done :)