Merge pull request #18374 from github/repo-sync

repo sync

content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/managing-code-scanning-alerts-for-your-repository.md

@@ -186,7 +186,8 @@ When you dismiss an alert:
 - It's dismissed in all branches.
 - The alert is removed from the number of current alerts for your project.
 - The alert is moved to the "Closed" list in the summary of alerts, from where you can reopen it, if required.
-- The reason why you closed the alert is recorded.
+- The reason why you closed the alert is recorded.{% if comment-dismissed-code-scanning-alert %} 
+- Optionally, you can comment on a dismissal to record the context of an alert dismissal.{% endif %}
 - Next time {% data variables.product.prodname_code_scanning %} runs, the same code won't generate an alert.
 
 {% if delete-code-scanning-alerts %}When you delete an alert:
@@ -219,8 +220,11 @@ To dismiss {% if delete-code-scanning-alerts %}or delete{% endif %} alerts:
 {% else %}
   ![List of alerts from {% data variables.product.prodname_code_scanning %}](/assets/images/enterprise/3.1/help/repository/code-scanning-click-alert.png)
 {% endif %}
-1. Review the alert, then click **Dismiss** and choose a reason for closing the alert.
-   ![Choosing a reason for dismissing an alert](/assets/images/help/repository/code-scanning-alert-close-drop-down.png)
+1. Review the alert, then click {% if comment-dismissed-code-scanning-alert %}**Dismiss alert** and choose, or type, a reason for closing the alert. 
+  ![Screenshot of code scanning alert with dropdown to choose dismissal reason emphasized](/assets/images/help/repository/code-scanning-alert-drop-down-reason.png)
+{% else %}**Dismiss** and choose a reason for closing the alert.
+  ![Choosing a reason for dismissing an alert](/assets/images/help/repository/code-scanning-alert-close-drop-down.png)
+{% endif %}
 
    {% data reusables.code-scanning.choose-alert-dismissal-reason %}
 

content/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/triaging-code-scanning-alerts-in-pull-requests.md

@@ -92,9 +92,11 @@ Anyone with push access to a pull request can fix a {% data variables.product.pr
 ## Dismissing an alert on your pull request
 
 An alternative way of closing an alert is to dismiss it. You can dismiss an alert if you don't think it needs to be fixed. {% data reusables.code-scanning.close-alert-examples %} If you have write permission for the repository, the **Dismiss** button is available in code annotations and in the alerts summary. When you click **Dismiss** you will be prompted to choose a reason for closing the alert.
-
+{% if comment-dismissed-code-scanning-alert %}
+![Screenshot of code scanning alert with dropdown to choose dismissal reason emphasized](/assets/images/help/repository/code-scanning-alert-drop-down-reason.png)
+{% else %}
 ![Choosing a reason for dismissing an alert](/assets/images/help/repository/code-scanning-alert-close-drop-down.png)
-
+{% endif %}
 {% data reusables.code-scanning.choose-alert-dismissal-reason %}
 
 {% data reusables.code-scanning.false-positive-fix-codeql %}

data/features/comment-dismissed-code-scanning-alert.yml

@@ -0,0 +1,5 @@
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>=3.6'
+  ghae: 'issue-2191'

data/reusables/code-scanning/choose-alert-dismissal-reason.md

@@ -1 +1,2 @@
-It's important to choose the appropriate reason from the drop-down menu as this may affect whether a query continues to be included in future analysis.
+It's important to choose the appropriate reason from the drop-down menu as this may affect whether a query continues to be included in future analysis. {% if comment-dismissed-code-scanning-alert %}Optionally, you can comment on a dismissal to record the context of an alert dismissal. The dismissal comment is added to the alert timeline and can be used as justification during auditing and reporting. You can retrieve or set a comment by using the code scanning REST API. The comment is contained in `dismissed_comment` for the `alerts/{alert_number}` endpoint. For more information, see "[Code Scanning](/rest/code-scanning#update-a-code-scanning-alert)."
+{% endif %}