Add vulnerability-alerts permission documentation

Document the new vulnerability-alerts permission for GITHUB_TOKEN.
This read-only permission allows workflows to read Dependabot alerts.

- Add feature flag for staged rollout (fpt/ghec first)
- Add vulnerability-alerts row to scope descriptions
- Add to available permissions list
- Update security-events description (gated behind feature flag)

Author: salmanmkc

data/features/vulnerability-alerts-permission.yml

@@ -0,0 +1,4 @@
+# Vulnerability alerts permission for GITHUB_TOKEN
+versions:
+  fpt: '*'
+  ghec: '*'

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 %}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. 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 %} |