Make "Enable SAST/Secret Detection" MR title and description more self-documenting
Problem to solve
When people enable SAST or Secret Detection via an MR, the process can be confusing (see #357511 (closed)).
We have a preferred flow we want people to go through:
- Enable via MR
- Review pipeline results (in MR widget if user has Ultimate)
- Change settings if needed
- Merge MR to activate SAST going forward
But we don't do a great job making it clear that:
- SAST isn't enabled until you merge the MR
- You should look at the findings before merging to avoid polluting your Security Dashboard with a bunch of errors (like if you forget to ignore a directory)
- We may have reformatted your CI file
Proposal
- Shorten the MR title from "Configure SAST in
.gitlab-ci.yml, creating this file if does not already exist" to "Enable GitLab SAST" - Expand the MR description to clearly state what has been done, what users should do before merging, and how to learn more.
Proposed copy changes are outlined in the following Google doc. Please see the design section of this issue for a mockup of the proposal.
Inspiration/related work
Renovate has a pretty nice initial Pull Request-based onboarding experience. Here's an example PR. The description is a low-context communication and dynamically updates as the renovate.json config is changed. As an MVC we don't need to dynamically update the description, but could model our text after this approach.
Intended users
Possible personas
- Delaney (Development Team Lead)
- Sasha (Software Developer)
- Sam (Security Analyst)
- Alex (Security Operations Engineer)
Feature Usage Metrics
This is an evolution of an existing feature, so new metrics may not be appropriate. However, we could have a feedback issue and refer to it in the issue description—something like, "How could GitLab make this MR clearer? Let us know!."
