Add vulnerability-alerts permission documentation (#60783)

Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>

Author: salmanmkc

data/features/vulnerability-alerts-permission.yml

@@ -0,0 +1,6 @@
+# Vulnerability alerts permission for GITHUB_TOKEN
+# GHES support will be added when the feature ships to GHES
+versions:
+  fpt: '*'
+  ghec: '*'
+  # ghes: '>=3.XX' # Uncomment when vulnerability-alerts permission ships to GHES

data/reusables/actions/github-token-available-permissions.md

@@ -17,7 +17,8 @@ permissions:
   pull-requests: read|write|none{% ifversion projects-v1 %}
   repository-projects: read|write|none{% endif %}
   security-events: read|write|none
-  statuses: read|write|none
+  statuses: read|write|none{% ifversion vulnerability-alerts-permission %}
+  vulnerability-alerts: read|none{% endif %}
 ```
 
 If you specify the access for any of these permissions, all of those that are not specified are set to `none`.

data/reusables/actions/github-token-scope-descriptions.md

@@ -28,5 +28,8 @@ Available permissions and details of what each allows an action to do:
 | {% ifversion projects-v1 %} |
 |  `repository-projects` | Work with GitHub projects (classic). For example, `repository-projects: write` permits an action to add a column to a project (classic). For more information, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-projects). |
 | {% endif %} |
-|  `security-events` | Work with GitHub code scanning alerts. For example, `security-events: read` permits an action to list the code scanning alerts for the repository, and `security-events: write` allows an action to update the status of a code scanning alert. For more information, see [Repository permissions for 'Code scanning alerts'](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-code-scanning-alerts). <br><br> Dependabot and secret scanning alerts cannot be read with this permission and require a GitHub App or a {% data variables.product.pat_generic %}. For more information, see [Repository permissions for 'Dependabot alerts'](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-dependabot-alerts) and [Repository permissions for 'Secret scanning alerts'](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-secret-scanning-alerts) in "Permissions required for GitHub Apps." |
+|  `security-events` | Work with GitHub code scanning alerts. For example, `security-events: read` permits an action to list the code scanning alerts for the repository, and `security-events: write` allows an action to update the status of a code scanning alert. For more information, see [Repository permissions for "Code scanning alerts"](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-code-scanning-alerts). <br><br> {% ifversion vulnerability-alerts-permission %}For Dependabot alerts, use the `vulnerability-alerts` permission. Secret scanning alerts cannot be read with this permission and require a GitHub App or a {% data variables.product.pat_generic %}. For more information, see [Repository permissions for "Secret scanning alerts"](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-secret-scanning-alerts) in "Permissions required for GitHub Apps."{% else %}Dependabot and secret scanning alerts cannot be read with this permission and require a GitHub App or a {% data variables.product.pat_generic %}. For more information, see [Repository permissions for "Dependabot alerts"](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-dependabot-alerts) and [Repository permissions for "Secret scanning alerts"](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-secret-scanning-alerts) in "Permissions required for GitHub Apps."{% endif %} |
 | `statuses` | Work with commit statuses. For example, `statuses:read` permits an action to list the commit statuses for a given reference. For more information, see [AUTOTITLE](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-commit-statuses). |
+| {% ifversion vulnerability-alerts-permission %} |
+|  `vulnerability-alerts` | Read Dependabot alerts. For example, `vulnerability-alerts: read` permits an action to list Dependabot alerts for the repository. Only `read` and `none` are supported; `write` is not valid. When `write-all` or `read-all` is used, `vulnerability-alerts` is automatically included as `read`. For more information, see [Repository permissions for "Dependabot alerts"](/rest/overview/permissions-required-for-github-apps?apiVersion=2022-11-28#repository-permissions-for-dependabot-alerts). |
+| {% endif %} |