Code scanning alerts link to GitHub issues to facilitate collaboration and work management [Public Preview] (#60609)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Laura Coursen <lecoursen@github.com>

Author: 3 people

content/code-security/concepts/code-scanning/about-code-scanning-alerts.md

@@ -68,6 +68,8 @@ If you configure {% data variables.product.prodname_code_scanning %} using {% da
 
 When {% data variables.product.prodname_code_scanning %} reports data-flow alerts, {% data variables.product.prodname_dotcom %} shows you how data moves through the code. {% data variables.product.prodname_code_scanning_caps %} allows you to identify the areas of your code that leak sensitive information, and that could be the entry point for attacks by malicious users.
 
+{% data reusables.code-scanning.track-alert-in-issue %}
+
 ### About alerts from multiple configurations
 
 You can run multiple configurations of code analysis on a repository, using different tools and targeting different languages or areas of the code. Each configuration of {% data variables.product.prodname_code_scanning %} generates a unique set of alerts. For example, an alert generated using the default {% data variables.product.prodname_codeql %} analysis with {% data variables.product.prodname_actions %} comes from a different configuration than an alert generated externally and uploaded via the {% data variables.product.prodname_code_scanning %} API.

content/code-security/concepts/code-scanning/code-scanning-alert-tracking-using-issues.md

@@ -0,0 +1,39 @@
+---
+title: Code scanning alert tracking using issues
+shortTitle: Alert tracking with issues
+intro: Connect security findings to your team's workflow by linking {% data variables.product.prodname_code_scanning %} alerts to issues for tracking and collaboration.
+permissions: People with write access for the repository can link {% data variables.product.prodname_code_scanning %} alerts to issues.
+versions:
+  feature: code-scanning-link-alert-to-issue
+contentType: concepts
+category:
+  - Find and fix code vulnerabilities
+---
+
+{% data reusables.code-scanning.alert-tracking-with-issues-preview-note %}
+
+{% data reusables.code-scanning.enterprise-enable-code-scanning %}
+
+## How alert-to-issue linking works
+
+When {% data variables.product.prodname_code_scanning %} identifies a vulnerability in your code, you can link the alert to a {% data variables.product.prodname_dotcom %} **issue** to track remediation work. This brings security fixes into your existing planning and project management workflow, making vulnerabilities visible in sprint planning, project boards, and team backlogs.
+
+Each alert can link to a single issue, while each issue can track up to 50 different alerts. This flexibility lets you group related vulnerabilities or track them individually, depending on your team's workflow.
+
+You can link alerts to issues in any repository where you have access and {% data variables.product.prodname_github_issues %} is enabled, not just the repository where the alert was found. This is useful when you track work in a central repository or use a separate issue tracker for security fixes.
+
+## Understanding synchronization behavior
+
+**Alert and issue statuses are not automatically synchronized.** Changes you make to an alert do not update the linked issue, and vice versa. This means:
+
+* When you fix the vulnerability and the alert automatically closes, the linked issue remains open until you manually close it.
+* When you close or reopen an issue, the alert status stays unchanged.
+* When you delete an issue, the link is removed from the alert page and alert list, but the alert itself remains open.
+
+## Best practices for managing linked alerts and issues
+
+**Track remediation progress clearly.** When you commit a fix, add a comment to the linked issue noting that the code is updated. After the next {% data variables.product.prodname_code_scanning %} run confirms the alert is closed, manually close the issue.
+
+**Use labels to show status.** Create issue labels like "code-fixed-awaiting-scan" or use project fields to indicate when a vulnerability is fixed but the issue is waiting for final verification and closure.
+
+**Assign responsibility.** Use issue assignees to make it clear who owns the remediation work, especially when security and development teams need to coordinate.

content/code-security/concepts/code-scanning/index.md

@@ -17,6 +17,7 @@ children:
   - /setup-types
   - /about-integration-with-code-scanning
   - /sarif-files
+  - /code-scanning-alert-tracking-using-issues
   - /merge-protection
   - /multi-repository-variant-analysis
   - /codeql

content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/assessing-code-scanning-alerts-for-your-repository.md

@@ -25,7 +25,7 @@ By default, the {% data variables.product.prodname_code_scanning %} alerts page
 {% data reusables.repositories.navigate-to-repo %}
 {% data reusables.repositories.sidebar-security %}
 {% data reusables.repositories.sidebar-code-scanning-alerts %}
-1. Optionally, use the free text search box or the dropdown menus to filter alerts. For example, you can filter by the tool that was used to identify alerts.
+1. Optionally, use the free text search box or the dropdown menus to filter alerts. For example, you can filter by the tool that was used to identify alerts.{% ifversion code-scanning-link-alert-to-issue %} Linked {% data variables.product.prodname_dotcom %} issues appear alongside their corresponding alerts in the list view.{% endif %}
 
    ![Screenshot of {% data variables.product.prodname_code_scanning %} alerts page. The search box and filter dropdown menus are outlined in dark orange.](/assets/images/help/repository/filter-code-scanning-alerts.png)
 

content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/index.md

@@ -12,6 +12,7 @@ redirect_from:
 children:
   - assessing-code-scanning-alerts-for-your-repository
   - triaging-code-scanning-alerts-in-pull-requests
+  - linking-code-scanning-alerts-to-github-issues
   - resolving-code-scanning-alerts
   - enabling-delegated-alert-dismissal-for-code-scanning
   - disabling-autofix-for-code-scanning

content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/linking-code-scanning-alerts-to-github-issues.md

@@ -0,0 +1,68 @@
+---
+title: Linking code scanning alerts to GitHub issues
+shortTitle: Track alerts in issues
+intro: Create or connect {% data variables.product.github %} issues to {% data variables.product.prodname_code_scanning %} alerts to track security fixes in your team's workflow.
+permissions: People with write access for the repository can link {% data variables.product.prodname_code_scanning %} alerts to issues.
+versions:
+  feature: code-scanning-link-alert-to-issue
+contentType: how-tos
+category:
+  - Find and fix code vulnerabilities
+---
+
+{% data reusables.code-scanning.alert-tracking-with-issues-preview-note %}
+
+{% data reusables.code-scanning.enterprise-enable-code-scanning %}
+
+When {% data variables.product.prodname_code_scanning %} identifies a vulnerability, you can link it to a new or existing {% data variables.product.github %} issue. This makes security fixes visible in your planning and project boards alongside your team's regular development work. For more information about how alert tracking works, see [AUTOTITLE](/code-security/concepts/code-scanning/code-scanning-alert-tracking-using-issues).
+
+## Creating an issue from an alert
+
+Create a new issue directly from a {% data variables.product.prodname_code_scanning %} alert, pre-populated with vulnerability details.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-security %}
+{% data reusables.repositories.sidebar-code-scanning-alerts %}
+{% data reusables.code-scanning.explore-alert %}
+1. On the right of the alert page, click **Tracking**.
+1. From the dropdown list, select **Create issue**.
+   * Select the repository to create the issue in.
+   * If applicable, select the template to use for your new issue.
+1. Fill in the issue, providing as much detail as possible.
+1. Optionally, assign the issue to a team member, add labels, or add it to a project.
+1. Click **Create**.
+
+The newly created issue automatically links to the alert. View it by clicking the issue icon below the alert name.
+
+## Linking an alert to an existing issue
+
+Connect an existing issue to a {% data variables.product.prodname_code_scanning %} alert.
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-security %}
+{% data reusables.repositories.sidebar-code-scanning-alerts %}
+{% data reusables.code-scanning.explore-alert %}
+1. On the right of the alert page, click **Tracking**.
+1. From the dropdown list, select **Add existing {% data variables.product.github %} issue**.
+1. Search by issue number or title, or select a different repository by clicking the Back icon.
+1. Click the issue you want to link.
+
+You can link to issues in different repositories, as long as you have access and {% data variables.product.prodname_github_issues %} is enabled.
+
+## Viewing linked issues
+
+Once you link an issue to an alert, you can view the linked issue in two places:
+
+* **On the alert detail page**: Click the issue icon below the alert name to navigate to the full issue details.
+* **In the list of {% data variables.product.prodname_code_scanning %} alerts**: Linked issues appear alongside their corresponding alerts in the main alerts list view.
+
+## Changing or unlinking a linked issue
+
+{% data reusables.repositories.navigate-to-repo %}
+{% data reusables.repositories.sidebar-security %}
+{% data reusables.repositories.sidebar-code-scanning-alerts %}
+{% data reusables.code-scanning.explore-alert %}
+1. On the right of the alert page, click **Tracking**.
+1. Click **Change or remove issue**.
+
+When you unlink an issue from an alert, the link is removed from the alert page and alert list. The issue itself remains unchanged.

content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolving-code-scanning-alerts.md

@@ -80,6 +80,8 @@ Within 30 seconds, {% data variables.product.prodname_copilot_short %} will open
 
 Anyone with write permission for a repository can fix an alert by committing a correction to the code. If the repository has {% data variables.product.prodname_code_scanning %} scheduled to run on pull requests, it's best to raise a pull request with your correction. This will trigger {% data variables.product.prodname_code_scanning %} analysis of the changes and test that your fix doesn't introduce any new problems. For more information, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests).
 
+{% data reusables.code-scanning.track-alert-in-issue %}
+
 You can use the free text search or the filters to display a subset of alerts and then in turn mark all matching alerts as closed.
 
 Alerts may be fixed in one branch but not in another. You can use the "branch" filter, on the summary of alerts, to check whether an alert is fixed in a particular branch.

content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triaging-code-scanning-alerts-in-pull-requests.md

@@ -71,6 +71,8 @@ You can comment on any {% data variables.product.prodname_code_scanning %} alert
 
 You can choose to require all conversations in a pull request, including those on {% data variables.product.prodname_code_scanning %} alerts, to be resolved before a pull request can be merged. For more information, see [AUTOTITLE](/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches#require-conversation-resolution-before-merging).
 
+{% data reusables.code-scanning.track-alert-in-issue %}
+
 ## Fixing an alert on your pull request
 
 Anyone with push access to a pull request can fix a {% data variables.product.prodname_code_scanning %} alert that's identified on that pull request. If you commit changes to the pull request this triggers a new run of the pull request checks. If your changes fix the problem, the alert is closed and the annotation removed.

data/features/code-scanning-link-alert-to-issue.yml

@@ -0,0 +1,5 @@
+# Reference: #20489 - Code scanning alerts link to GitHub issues to facilitate collaboration and work management
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>3.21'

data/reusables/code-scanning/alert-tracking-with-issues-preview-note.md

@@ -0,0 +1,2 @@
+> [!NOTE]
+> {% data variables.product.prodname_code_scanning_caps %} alert tracking using {% data variables.product.github %} issues is currently in {% data variables.release-phases.public_preview %} and subject to change.