diff --git a/Dockerfile b/Dockerfile index 4588162de93a..163187add267 100644 --- a/Dockerfile +++ b/Dockerfile @@ -10,7 +10,7 @@ # --------------------------------------------------------------- # To update the sha: # https://github.com/github/gh-base-image/pkgs/container/gh-base-image%2Fgh-base-noble -FROM ghcr.io/github/gh-base-image/gh-base-noble:20260708-113537-g661fe65de@sha256:894162a6b21fc03da8ba889760592e6e223ba76f3067723f93bd1e49aff1c46b AS base +FROM ghcr.io/github/gh-base-image/gh-base-noble:20260713-090615-gb0d388add@sha256:8708e26b53b2304cf8d933be5e8fbca4fa4d07b3ba6e4be238372a5d3029e443 AS base # Install curl for Node install and determining the early access branch # Install git for cloning docs-early-access & translations repos diff --git a/assets/images/help/code-quality/all-findings-overview-repo.png b/assets/images/help/code-quality/all-findings-overview-repo.png index 5578e830c16f..ca3911d4a350 100644 Binary files a/assets/images/help/code-quality/all-findings-overview-repo.png and b/assets/images/help/code-quality/all-findings-overview-repo.png differ diff --git a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md index 2ed70175a56b..87f650274b2e 100644 --- a/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md +++ b/content/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise.md @@ -120,3 +120,20 @@ Across all of your enterprise's organizations, you can allow or disallow people > This policy controls the use of {% data variables.copilot.copilot_autofix_short %} on results found by {% data variables.product.prodname_code_scanning %} security queries only. {% data variables.copilot.copilot_autofix_short %} is an integral part of {% data variables.product.prodname_code_quality %} and cannot be disabled for that feature. {% endif %} + +{% ifversion ai-powered-security-detections %} + +## Enforcing a policy to manage the use of AI-powered security detections in your enterprise's repositories + +As an enterprise owner, you can control whether organization and repository administrators can enable AI-powered security detections for their organizations and repositories. This policy is set to "Not allowed" by default. + +Allowing AI-powered security detections at the enterprise level does not enable the feature. Organization administrators must still explicitly enable AI-powered security detections. Repository administrators can opt-out of the feature. + +This policy only takes effect if {% data variables.product.prodname_codeql %} default setup is enabled. + +{% data reusables.enterprise-accounts.access-enterprise %} +{% data reusables.enterprise-accounts.policies-tab %} +{% data reusables.enterprise-accounts.code-security-and-analysis-policies %} +1. Under "AI Findings", select the dropdown menu and click a policy. + +{% endif %} diff --git a/content/authentication/authenticating-with-single-sign-on/authorizing-an-app-for-single-sign-on.md b/content/authentication/authenticating-with-single-sign-on/authorizing-an-app-for-single-sign-on.md index 0ad4e81e9a73..e6a5ef8d8bb7 100644 --- a/content/authentication/authenticating-with-single-sign-on/authorizing-an-app-for-single-sign-on.md +++ b/content/authentication/authenticating-with-single-sign-on/authorizing-an-app-for-single-sign-on.md @@ -24,11 +24,11 @@ Apps are automatically authorized for all of the organizations you have an SSO s If you sign into an app but it is unable to access an organization you belong to, first check that the app is approved or installed for the organization. If it is, you then need to sign into that organization's SSO providers using the following steps: -1. Go to your [organization settings](https://github.com/settings/organizations). -1. Under "Single sign-on", find the organization you need to authenticate to, and click **Sign in**. +1. Go to your [single sign-on settings](https://github.com/settings/sso). +1. Find the organization you need to authenticate to, and click **Sign in**. If your enterprise manages SSO for your organization, signing in to one organization in the enterprise works as an SSO session for all organizations in the enterprise. -1. Try to sign into the the app again. When you are authorizing the app you will see the organizations you've signed into and be able to request or install the app for those organizations. +1. Try to sign into the app again. When you are authorizing the app, you will see the organizations you've signed into and be able to request or install the app for those organizations. For more information, see [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-a-third-party), [AUTOTITLE](/apps/using-github-apps/installing-a-github-app-from-github-marketplace-for-your-organizations), and [AUTOTITLE](/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner). diff --git a/content/code-security/concepts/code-scanning/ai-powered-security-detections.md b/content/code-security/concepts/code-scanning/ai-powered-security-detections.md new file mode 100644 index 000000000000..6015c3efbe5b --- /dev/null +++ b/content/code-security/concepts/code-scanning/ai-powered-security-detections.md @@ -0,0 +1,77 @@ +--- +title: AI-powered security detections in pull requests +shortTitle: AI-powered security detections +allowTitleToDifferFromFilename: true +intro: 'AI-powered security detections use an AI-based scanning engine to find security vulnerabilities in pull requests for languages and frameworks not covered by {% data variables.product.prodname_codeql %}.' +versions: + feature: ai-powered-security-detections +contentType: concepts +category: + - Find and fix code vulnerabilities +--- + +> [!NOTE] +> AI-powered security detections are currently in {% data variables.release-phases.public_preview %} and subject to change. + +AI-powered security detections are additional security findings produced by an AI-based scanning engine that runs on pull requests and complements {% data variables.product.prodname_codeql %}. Unlike {% data variables.product.prodname_codeql %} alerts, AI-powered findings are only available on pull requests and do not appear as backlog alerts in the repository's security view. + +While {% data variables.product.prodname_codeql %} provides high-precision static analysis for a specific set of supported languages and queries, many repositories use languages and frameworks that {% data variables.product.prodname_codeql %} does not cover. AI-powered detections expand {% data variables.product.prodname_code_scanning %} coverage into these areas, helping you find vulnerabilities without adding new tools or configuration. + +During the {% data variables.release-phases.public_preview %}, AI-powered security detections require a {% data variables.product.prodname_GHAS %} license and a {% data variables.product.prodname_copilot %} license. + +Usage consumes {% data variables.product.prodname_ai_credits_short %}. See [AUTOTITLE](/copilot/concepts/billing/usage-based-billing-for-organizations-and-enterprises). + +## How AI-powered security detections work + +AI-powered security detections run automatically on pull requests in repositories where {% data variables.product.prodname_codeql %} default setup is enabled and AI-powered detections have been opted into. The AI-based scan is triggered on pull request creation and after each new commit, the same as {% data variables.product.prodname_codeql %}. + +AI-powered findings are advisory and do not block pull request merges. They provide signals about where code security can be improved without interrupting your workflow. + +The AI scanning engine works directly with the code in the pull request and does not require a build system. It uses tools such as code search to gather additional context from the repository when deciding whether to flag an issue. It uses its own specialized prompts and does not use custom instruction files such as `/.github/copilot-instructions.md` or `/CLAUDE.md`. + +The AI scan runs independently of {% data variables.product.prodname_codeql %}'s status. If {% data variables.product.prodname_codeql %} default setup fails or is in a waiting state, AI-powered detections will still run. + +Results are posted to the pull request as they are found. If the {% data variables.product.prodname_codeql %} scan takes longer to complete, you may see AI-powered findings before {% data variables.product.prodname_codeql %} results appear, or vice versa. + +## How findings appear on pull requests + +AI-powered findings appear alongside {% data variables.product.prodname_codeql %} alerts on the **Conversation** and **Files changed** tabs of a pull request. Each AI-powered finding is labeled with an "AI" indicator so you can distinguish it from {% data variables.product.prodname_codeql %} alerts. + +Each finding includes a description of the security issue and an explanation of the risk. Most findings also include a suggested remediation, but not every finding has one. Where a suggested remediation is available, {% data variables.copilot.copilot_autofix_short %} is included and provides a recommended code change to fix the issue, the same way it does for {% data variables.product.prodname_codeql %} alerts. Findings also include a thumbs up/down feedback mechanism that helps improve detection quality over time. + +## Limitations + +* AI-powered security detections analyze pull requests only. Full repository scans are not supported. +* AI-powered findings cannot yet be used in rulesets to enforce merge requirements +* Detection categories and supported languages may change as the feature evolves. +* As with any AI-based tool, findings may include false positives. Use the feedback mechanism to report inaccurate results. + +## Supported languages + +AI-powered security detections are designed to cover languages and frameworks that are not currently supported by {% data variables.product.prodname_codeql %}. This includes, but is not limited to, languages such as PHP, Shell/Bash, Terraform configuration (HCL), and Dockerfiles, as well as framework coverage gaps such as JSP for Java and Blazor for C#. + +For a full list of languages supported by {% data variables.product.prodname_codeql %}, see [AUTOTITLE](/code-security/concepts/code-scanning/codeql/about-code-scanning-with-codeql#supported-languages-and-frameworks). + +## Detection categories + +AI-powered security detections currently cover the following categories. These categories describe how findings are classified. The AI scanner may evolve over time as models improve. + +* **String injection** — Unsafe string-built SQL, HTML, shell, JSON, or YAML with missing or incorrect escaping or sanitization. +* **Weak cryptography** — Weak algorithms, small keys, insecure randomness, missing encryption, or weak password hashing. +* **Broken access control** — Path traversal, CSRF gaps, or user-driven open redirects. +* **Sensitive data exposure** — Secrets, tokens, passwords, or stack traces stored, logged, or sent without adequate protection. +* **Security misconfiguration** — Risky defaults or settings, such as disabling security controls or enabling debug features. +* **Authentication failures** — Missing TLS or validation, insecure authentication flows, or missing rate limiting. +* **Data integrity failures** — Unsafe deserialization, HTTP for sensitive actions, prototype pollution, or executing untrusted content. +* **Server-side request forgery (SSRF)** — Server fetches attacker-controlled URLs, hosts, or protocols. +* **Supply chain risks** — Unpinned third-party actions, packages, or images, or downloads without integrity checks. + +## Enabling AI-powered security detections + +AI-powered security detections are not allowed at the enterprise level by default and disabled at the organization and repository levels. Enterprise administrators must explicitly allow the feature before organizations can enable it. Organization administrators must explicitly opt in to the feature. Repository administrators can opt-out of the feature. Additionally, you need to have the {% data variables.product.prodname_codeql %} default setup enabled. + +You do not need to select a model to enable AI-powered security detections. + +* **Enterprise**: The **AI Findings** policy under "Code Security" controls whether organizations can enable the feature. See [AUTOTITLE](/admin/enforcing-policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-code-security-and-analysis-for-your-enterprise#enforcing-a-policy-to-manage-the-use-of-ai-powered-security-detections-in-your-enterprises-repositories). +* **Organization**: The **AI findings** setting under "Code scanning" enables AI-powered detections for repositories in the organization. See [AUTOTITLE](/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/configuring-global-security-settings-for-your-organization#enabling-ai-powered-security-detections). +* **Repository**: The **AI findings** toggle under "Code scanning" enables or disables AI-powered detections for the individual repository. Repositories inherit the organization setting but can opt out individually. diff --git a/content/code-security/concepts/code-scanning/autofix-for-code-scanning.md b/content/code-security/concepts/code-scanning/autofix-for-code-scanning.md new file mode 100644 index 000000000000..02ee8f5d6526 --- /dev/null +++ b/content/code-security/concepts/code-scanning/autofix-for-code-scanning.md @@ -0,0 +1,45 @@ +--- +title: About autofix for code scanning +shortTitle: Autofix +allowTitleToDifferFromFilename: true +intro: 'Autofix provides targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts and avoid introducing new security vulnerabilities.' +product: '{% data reusables.rai.code-scanning.gated-feature-autofix %}' +versions: + feature: code-scanning-autofix +contentType: concepts +category: + - Find and fix code vulnerabilities +redirect_from: + - /code-security/concepts/code-scanning/copilot-autofix-for-code-scanning +--- + +Autofix provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts so you can avoid introducing new security vulnerabilities. The potential fixes are generated automatically by large language models (LLMs) using data from the codebase and from {% data variables.product.prodname_code_scanning %} analysis. + +## How autofix works + +Autofix translates the description and location of a {% data variables.product.prodname_code_scanning %} alert into code changes that may fix it. It interfaces with the large language model {% data variables.copilot.copilot_gpt_53_codex %} from OpenAI, which has sufficient generative capabilities to produce both suggested fixes in code and explanatory text for those fixes. + +There are two ways to get a fix for an alert: agentic autofix and {% data variables.copilot.copilot_autofix_short %}. If {% data variables.copilot.copilot_cloud_agent %} is available in a repository, assigning an alert uses agentic autofix instead of {% data variables.copilot.copilot_autofix_short %}. + +## Agentic autofix + +> [!NOTE] This feature is currently in public preview and is subject to change. + +Assign a {% data variables.product.prodname_code_scanning %} alert to {% data variables.product.prodname_copilot_short %} to have it resolve the alert for you. Assigning an alert starts an agent session: {% data variables.copilot.copilot_cloud_agent %} calls tools to explore your codebase beyond the affected file, generates a fix, validates it (for example, by re-running {% data variables.product.prodname_codeql %}), and iterates until it opens a pull request with the changes. See [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts#fixing-alerts-with-copilot). + +Keep the following in mind: + +* Agentic autofix requires {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_autofix_short %} to be available in the repository. If {% data variables.copilot.copilot_cloud_agent %} isn't available, assigning an alert falls back to {% data variables.copilot.copilot_autofix_short %} instead. +* Each agentic autofix session is billed as a {% data variables.copilot.copilot_cloud_agent %} session and consumes {% data variables.product.prodname_ai_credits_short %}. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent#copilot-cloud-agent-usage-costs). +* {% data variables.product.prodname_copilot_short %} follows any custom instructions configured for the repository or organization when it generates a fix. +* Agentic autofix works on a best-effort basis. {% data variables.product.prodname_copilot_short %} validates fixes by re-running {% data variables.product.prodname_codeql %} using the code-scanning query suite, so it can't confirm that a fix resolves alerts generated by custom queries or the security-extended query suite. Fix quality for alerts from third-party tools is also not guaranteed. + +## Getting a suggested fix with {% data variables.copilot.copilot_autofix_short %} + +{% data variables.copilot.copilot_autofix_short %} generates a single suggested fix for an alert, which you review and apply yourself. + +You do not need a subscription to {% data variables.product.prodname_copilot %} to use {% data variables.copilot.copilot_autofix %}, and it does not consume {% data variables.product.prodname_ai_credits_short %}. {% data variables.copilot.copilot_autofix_short %} is available to all public repositories on {% data variables.product.prodname_dotcom_the_website %}, as well as internal or private repositories owned by organizations and enterprises that have a license for {% data variables.product.prodname_GH_code_security %}. + +{% data variables.copilot.copilot_autofix_short %} is allowed by default and enabled for every repository that uses {% data variables.product.prodname_codeql %}, regardless of whether it uses default or advanced setup for {% data variables.product.prodname_code_scanning %}. There is no separate step to enable {% data variables.copilot.copilot_autofix_short %}: enabling {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %} is sufficient. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). + +Administrators at the enterprise, organization, and repository levels can choose to disable {% data variables.copilot.copilot_autofix_short %}. If {% data variables.copilot.copilot_autofix_short %} has been disabled at your level, you can re-enable it by following the same steps used to disable it and selecting the option to allow {% data variables.copilot.copilot_autofix_short %}. To learn how to manage {% data variables.copilot.copilot_autofix_short %} at each level, see [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning). diff --git a/content/code-security/concepts/code-scanning/copilot-autofix-for-code-scanning.md b/content/code-security/concepts/code-scanning/copilot-autofix-for-code-scanning.md deleted file mode 100644 index 87ed9e599475..000000000000 --- a/content/code-security/concepts/code-scanning/copilot-autofix-for-code-scanning.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: About Copilot Autofix for code scanning -shortTitle: Copilot Autofix -allowTitleToDifferFromFilename: true -intro: '{% data variables.copilot.copilot_autofix_short %} provides targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts and avoid introducing new security vulnerabilities.' -product: '{% data reusables.rai.code-scanning.gated-feature-autofix %}' -versions: - feature: code-scanning-autofix -contentType: concepts -category: - - Find and fix code vulnerabilities ---- - -{% data variables.copilot.copilot_autofix_short %} is an expansion of {% data variables.product.prodname_code_scanning %} that provides you with targeted recommendations to help you fix {% data variables.product.prodname_code_scanning %} alerts so you can avoid introducing new security vulnerabilities. The potential fixes are generated automatically by large language models (LLMs) using data from the codebase and from {% data variables.product.prodname_code_scanning %} analysis. - -## How {% data variables.copilot.copilot_autofix_short %} works - -{% data variables.copilot.copilot_autofix_short %} translates the description and location of an alert into code changes that may fix the alert. It interfaces with the large language model {% data variables.copilot.copilot_gpt_53_codex %} from OpenAI, which has sufficient generative capabilities to produce both suggested fixes in code and explanatory text for those fixes. - -## Enabling and managing {% data variables.copilot.copilot_autofix_short %} - -You do not need a subscription to {% data variables.product.prodname_copilot %} to use {% data variables.copilot.copilot_autofix %}. {% data variables.copilot.copilot_autofix_short %} is available to all public repositories on {% data variables.product.prodname_dotcom_the_website %}, as well as internal or private repositories owned by organizations and enterprises that have a license for {% data variables.product.prodname_GH_code_security %}. - -{% data variables.copilot.copilot_autofix_short %} is allowed by default and enabled for every repository that uses {% data variables.product.prodname_codeql %}, regardless of whether it uses default or advanced setup for {% data variables.product.prodname_code_scanning %}. There is no separate step to enable {% data variables.copilot.copilot_autofix_short %}: enabling {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %} is sufficient. See [AUTOTITLE](/code-security/code-scanning/enabling-code-scanning/configuring-default-setup-for-code-scanning). - -Administrators at the enterprise, organization, and repository levels can choose to disable {% data variables.copilot.copilot_autofix_short %}. If {% data variables.copilot.copilot_autofix_short %} has been disabled at your level, you can re-enable it by following the same steps used to disable it and selecting the option to allow {% data variables.copilot.copilot_autofix_short %}. To learn how to manage {% data variables.copilot.copilot_autofix_short %} at each level, see [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning). diff --git a/content/code-security/concepts/code-scanning/index.md b/content/code-security/concepts/code-scanning/index.md index 9245a2090c4d..d1ec8d040763 100644 --- a/content/code-security/concepts/code-scanning/index.md +++ b/content/code-security/concepts/code-scanning/index.md @@ -13,7 +13,8 @@ children: - /code-scanning - /code-scanning-alerts - /risk-assessment - - /copilot-autofix-for-code-scanning + - /autofix-for-code-scanning + - /ai-powered-security-detections - /setup-types - /integration-with-code-scanning - /sarif-files diff --git a/content/code-security/getting-started/github-security-features.md b/content/code-security/getting-started/github-security-features.md index 500c1b80cee2..8ea62552d109 100644 --- a/content/code-security/getting-started/github-security-features.md +++ b/content/code-security/getting-started/github-security-features.md @@ -203,6 +203,14 @@ Get automatically generated fixes for {% data variables.product.prodname_code_sc {% endif %} +{% ifversion ai-powered-security-detections %} + +### AI-powered security detections + +Find vulnerabilities in languages and frameworks not covered by {% data variables.product.prodname_codeql %} with an AI-based scanning engine that runs during pull request review. See [AUTOTITLE](/code-security/concepts/code-scanning/ai-powered-security-detections). + +{% endif %} + ### {% data variables.dependabot.custom_rules_caps %} for {% data variables.product.prodname_dependabot %} {% data reusables.dependabot.dependabot-custom-rules-ghas %} diff --git a/content/code-security/getting-started/quickstart-for-securing-your-repository.md b/content/code-security/getting-started/quickstart-for-securing-your-repository.md index 191343232ef6..28bd8e455277 100644 --- a/content/code-security/getting-started/quickstart-for-securing-your-repository.md +++ b/content/code-security/getting-started/quickstart-for-securing-your-repository.md @@ -123,7 +123,7 @@ You can configure {% data variables.product.prodname_code_scanning %} to automat 1. If "{% data variables.product.prodname_code_security %}" or "{% data variables.product.prodname_GHAS %}" is not already enabled, click **Enable**. 1. To the right of "CodeQL analysis", select **Set up** {% octicon "triangle-down" aria-hidden="true" aria-label="triangle-down" %}, then click **Default**. 1. In the pop-up window that appears, review the default configuration settings for your repository, then click **Enable {% data variables.product.prodname_codeql %}**.{% ifversion code-scanning-autofix %} -1. Choose whether you want to enable addition features, such as {% data variables.copilot.copilot_autofix_short %}.{% endif %} +1. Choose whether you want to enable addition features, such as {% data variables.copilot.copilot_autofix_short %} or AI-powered security detections.{% endif %} As an alternative to default setup, you can use advanced setup, which generates a workflow file you can edit to customize your {% data variables.product.prodname_code_scanning %} with {% data variables.product.prodname_codeql %}. For more information, see [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/configuring-advanced-setup-for-code-scanning#configuring-advanced-setup-for-code-scanning-with-codeql). diff --git a/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning.md b/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning.md index 32852dab667c..9e8ec940aac9 100644 --- a/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning.md +++ b/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning.md @@ -1,8 +1,8 @@ --- -title: Disabling Copilot Autofix for code scanning security alerts -shortTitle: Disable Copilot Autofix +title: Disabling autofix for code scanning security alerts +shortTitle: Disable autofix allowTitleToDifferFromFilename: true -intro: You can block availability of {% data variables.copilot.copilot_autofix %} for security alerts for an enterprise or disable {% data variables.copilot.copilot_autofix %} at the organization and repository level. +intro: 'You can disable {% data variables.copilot.copilot_autofix_short %}, which also blocks agentic autofix, for an enterprise, organization, or repository.' product: '{% data reusables.rai.code-scanning.gated-feature-autofix %}' versions: feature: code-scanning-autofix @@ -13,16 +13,27 @@ category: - Find and fix code vulnerabilities --- -{% data reusables.rai.code-scanning.copilot-autofix-note %} +## Disabling agentic autofix + +Disabling agentic autofix can be done in two ways: + +1. By disabling {% data variables.copilot.copilot_autofix_short %} since agentic autofix relies on the same underlying setting. For instructions, see the sections below. +1. By opting repositories out of {% data variables.copilot.copilot_cloud_agent %}. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/access-management#opting-repositories-out-of-copilot-cloud-agent). + +For more information about agentic autofix, see [AUTOTITLE](/code-security/concepts/code-scanning/autofix-for-code-scanning#agentic-autofix). + +## Disabling {% data variables.copilot.copilot_autofix_short %} + +You can disable {% data variables.copilot.copilot_autofix_short %} at the enterprise, organization, or repository level. Disabling {% data variables.copilot.copilot_autofix_short %} at any level will close all open {% data variables.copilot.copilot_autofix_short %} suggestions that were added as comments on {% data variables.product.prodname_code_scanning %} alerts in pull requests. If {% data variables.copilot.copilot_autofix_short %} is later re-enabled, suggestions will only be generated for pull requests opened after that point, or after re-running {% data variables.product.prodname_code_scanning %} security analysis on existing pull requests. > [!NOTE] > {% data variables.copilot.copilot_autofix_short %} is an integral part of {% data variables.product.prodname_code_quality %} and will continue to run on code quality results even when it is disabled for code security results. -For more information about {% data variables.copilot.copilot_autofix_short %}, see [AUTOTITLE](/code-security/concepts/code-scanning/copilot-autofix-for-code-scanning). +For more information about {% data variables.copilot.copilot_autofix_short %}, see [AUTOTITLE](/code-security/concepts/code-scanning/autofix-for-code-scanning). -## Blocking use of {% data variables.copilot.copilot_autofix_short %} for an enterprise +### Blocking use of {% data variables.copilot.copilot_autofix_short %} for an enterprise Enterprise administrators can disallow {% data variables.copilot.copilot_autofix_short %} for security results in their enterprise. If you disallow {% data variables.copilot.copilot_autofix_short %} for an enterprise, {% data variables.copilot.copilot_autofix_short %} cannot be enabled for any organizations or repositories within the enterprise. @@ -35,7 +46,7 @@ Disallowing {% data variables.copilot.copilot_autofix_short %} at the enterprise {% data reusables.enterprise-accounts.code-security-and-analysis-policies %} 1. Under "{% data variables.copilot.copilot_autofix_short %}", use the dropdown menu to choose "Not allowed." -## Disabling {% data variables.copilot.copilot_autofix_short %} for an organization +### Disabling {% data variables.copilot.copilot_autofix_short %} for an organization If {% data variables.copilot.copilot_autofix_short %} is allowed at the enterprise level, organization administrators have the option to disable {% data variables.copilot.copilot_autofix_short %} for an organization. If you disable {% data variables.copilot.copilot_autofix_short %} for an organization, {% data variables.copilot.copilot_autofix_short %} cannot be enabled for any repositories within the organization. @@ -48,7 +59,7 @@ Disabling {% data variables.copilot.copilot_autofix_short %} at the organization For more information about configuring global {% data variables.product.prodname_code_scanning %} settings, see [AUTOTITLE](/code-security/securing-your-organization/enabling-security-features-in-your-organization/configuring-global-security-settings-for-your-organization#configuring-global-code-scanning-settings). -## Disabling {% data variables.copilot.copilot_autofix_short %} for a repository +### Disabling {% data variables.copilot.copilot_autofix_short %} for a repository If {% data variables.copilot.copilot_autofix_short %} is allowed at the enterprise level and enabled at the organization level, repository administrators have the option to disable {% data variables.copilot.copilot_autofix_short %} for a repository. Disabling {% data variables.copilot.copilot_autofix_short %} at the repository level will remove all open {% data variables.copilot.copilot_autofix_short %} suggestions that were added as comments on {% data variables.product.prodname_code_scanning %} alerts in pull requests across the repository. diff --git a/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts.md b/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts.md index 1fc35debd4eb..d7d9f2eb9a6b 100644 --- a/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts.md +++ b/content/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts.md @@ -27,59 +27,69 @@ category: ## Asking {% data variables.copilot.copilot_chat %} about {% data variables.product.prodname_code_scanning %} alerts -With a {% data variables.copilot.copilot_enterprise %} license, you can ask {% data variables.copilot.copilot_chat_short %} for help to better understand security alerts, including {% data variables.product.prodname_code_scanning %} alerts, in repositories in your organization. For more information, see [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). +With a {% data variables.copilot.copilot_enterprise %} license, you can ask {% data variables.copilot.copilot_chat_short %} for help to better understand security alerts, including {% data variables.product.prodname_code_scanning %} alerts, in repositories in your organization. See [AUTOTITLE](/copilot/using-github-copilot/asking-github-copilot-questions-in-githubcom#asking-questions-about-alerts-from-github-advanced-security-features). {% endif %} -{% ifversion code-scanning-autofix %} +{% ifversion copilot %} + +## Fixing alerts with {% data variables.product.prodname_copilot_short %} -## Generating suggested fixes for {% data variables.product.prodname_code_scanning %} alerts +> [!NOTE] +> This feature is in {% data variables.release-phases.public_preview %} and subject to change. {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_autofix_short %} must be available in the repository. -{% data variables.copilot.copilot_autofix %} can generate fixes for alerts identified by {% data variables.product.prodname_code_scanning %} analysis. Most {% data variables.product.prodname_codeql %} alert types are supported. See [AUTOTITLE](/code-security/concepts/code-scanning/copilot-autofix-for-code-scanning). +You can assign a {% data variables.product.prodname_code_scanning %} alert to {% data variables.product.prodname_copilot_short %} to have it fix the alert for you. Assigning the alert starts an agent session: {% data variables.copilot.copilot_cloud_agent %} explores your codebase, generates a fix, validates it, and opens a pull request. -{% data reusables.rai.code-scanning.copilot-autofix-note %} +Each agentic autofix session is billed as a {% data variables.copilot.copilot_cloud_agent %} session and consumes {% data variables.product.prodname_ai_credits_short %}. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent#copilot-cloud-agent-usage-costs). + +To assign an individual alert to {% data variables.product.prodname_copilot_short %}: {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-security %} {% data reusables.repositories.sidebar-code-scanning-alerts %} 1. Click the name of an alert. -1. If {% data variables.copilot.copilot_autofix_short %} can suggest a fix, at the top of the page, click **{% octicon "shield-check" aria-hidden="true" aria-label="shield-check" %} Generate fix**. -1. Once the suggested fix has been generated, at the bottom of the page, you can click **Create PR with fix** to automatically generate a pull request with the suggested fix. -A new branch is created from the default branch, the generated fix is committed and a draft pull request is created. You can test and edit the suggested fix as you would with any other fix. +1. At the top of the page, click **{% octicon "agent" aria-label="Open agents panel" %} Assign to {% data variables.product.prodname_copilot_short %}**. -You can also use the Autofix API for historical alerts endpoints to generate, get, and commit suggested fixes. +You can also assign alerts to {% data variables.product.prodname_copilot_short %} in bulk: -* [Create an autofix for a code scanning alert](/rest/code-scanning/code-scanning#create-an-autofix-for-a-code-scanning-alert) -* [Get the status of an autofix for a code scanning alert](/rest/code-scanning/code-scanning#get-the-status-of-an-autofix-for-a-code-scanning-alert) -* [Commit an autofix for a code scanning alert](/rest/code-scanning/code-scanning#commit-an-autofix-for-a-code-scanning-alert) +* From the {% data variables.product.prodname_code_scanning %} alerts backlog or from a security campaign, select between 1 and 25 alerts and assign them to {% data variables.product.prodname_copilot_short %}, which works to resolve the selected alerts in a single pull request. See [AUTOTITLE](/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign). +* Using the REST API, by setting the alert's assignee to `copilot-swe-agent[bot]`. See [AUTOTITLE](/rest/code-scanning/code-scanning#update-a-code-scanning-alert). -{% data variables.copilot.copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %} alerts won't be able to generate a fix for every alert in every situation. The feature operates on a best-effort basis and is not guaranteed to succeed 100% of the time. For information about the limitations of automatically generated fixes, see [Limitations of suggestions](/code-security/code-scanning/managing-code-scanning-alerts/about-autofix-for-codeql-code-scanning#limitations-of-suggestions). +Typically within a few minutes, {% data variables.product.prodname_copilot_short %} opens a draft pull request authored by {% data variables.product.prodname_copilot_short %}, with a summary of the fix and the validation steps taken. Review the agent session log for details, and comment on the pull request, mentioning {% data variables.product.prodname_copilot_short %}, to ask it to iterate. + +{% data variables.copilot.copilot_cloud_agent %} validates fixes on a best-effort basis. If it can't validate a fix, or thinks the alert might be a false positive, it says so in the pull request. {% endif %} -{% ifversion security-campaigns-assign-to-cca %} +{% ifversion code-scanning-autofix %} -## Assigning alerts to {% data variables.copilot.copilot_cloud_agent %} +## Generating a suggested fix ->[!NOTE] This option is currently in public preview and is subject to change. {% data variables.copilot.copilot_cloud_agent %} must be available in the repository. +{% ifversion copilot %}If {% data variables.copilot.copilot_cloud_agent %} isn't available in your repository, you can still use {% data variables.copilot.copilot_autofix %} to generate a one-step suggested fix for the alert.{% else %}{% data variables.copilot.copilot_autofix %} can generate fixes for alerts identified by {% data variables.product.prodname_code_scanning %} analysis. Most {% data variables.product.prodname_codeql %} alert types are supported.{% endif %} -You can assign {% data variables.product.prodname_copilot_short %} to apply an autofix. {% data variables.product.prodname_copilot_short %} analyzes the code scanning alert, creates a remediation plan, and implements the necessary code changes in a pull request. +{% data reusables.rai.code-scanning.copilot-autofix-note %} {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-security %} {% data reusables.repositories.sidebar-code-scanning-alerts %} 1. Click the name of an alert. -1. If an autofix has not been generated and {% data variables.copilot.copilot_autofix_short %} can suggest a fix, at the top of the page, click **{% octicon "shield-check" aria-hidden="true" aria-label="shield-check" %} Generate fix**. -1. In the right-side menu, click **Assignees**. -1. Select "Copilot". +1. If {% data variables.copilot.copilot_autofix_short %} can suggest a fix, at the top of the page, click **{% octicon "shield-check" aria-hidden="true" aria-label="shield-check" %} Generate fix**. +1. Once the suggested fix has been generated, at the bottom of the page, you can click **Create PR with fix** to automatically generate a pull request with the suggested fix. +A new branch is created from the default branch, the generated fix is committed and a draft pull request is created. You can test and edit the suggested fix as you would with any other fix. -Within 30 seconds, {% data variables.product.prodname_copilot_short %} will open a pull request to address the alert and will include a summary of the fixes and details of the changes made. Once created, the pull request is shown in the "Development" section. +You can also use the Autofix API for historical alerts endpoints to generate, get, and commit suggested fixes. + +* [Create an autofix for a code scanning alert](/rest/code-scanning/code-scanning#create-an-autofix-for-a-code-scanning-alert) +* [Get the status of an autofix for a code scanning alert](/rest/code-scanning/code-scanning#get-the-status-of-an-autofix-for-a-code-scanning-alert) +* [Commit an autofix for a code scanning alert](/rest/code-scanning/code-scanning#commit-an-autofix-for-a-code-scanning-alert) + +{% data variables.copilot.copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %} alerts won't be able to generate a fix for every alert in every situation. The feature operates on a best-effort basis and is not guaranteed to succeed 100% of the time. For information about the limitations of automatically generated fixes, see [Limitations of suggestions](/code-security/code-scanning/managing-code-scanning-alerts/about-autofix-for-codeql-code-scanning#limitations-of-suggestions). {% endif %} ## Fixing an alert {% ifversion code-scanning-autofix %}manually{% endif %} -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). +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. 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 %} @@ -92,7 +102,7 @@ Alerts may be fixed in one branch but not in another. You can use the "branch" f {% data reusables.code-scanning.filter-non-default-branches %} > [!NOTE] -> If you run {% data variables.product.prodname_code_scanning %} using multiple configurations, the same alert will sometimes be generated by more than one configuration. Unless you run all configurations regularly, you may see alerts that are fixed in one configuration but not in another. These stale configurations and alerts can be removed from a branch. For more information, see [Removing stale configurations and alerts from a branch](#removing-stale-configurations-and-alerts-from-a-branch). +> If you run {% data variables.product.prodname_code_scanning %} using multiple configurations, the same alert will sometimes be generated by more than one configuration. Unless you run all configurations regularly, you may see alerts that are fixed in one configuration but not in another. These stale configurations and alerts can be removed from a branch. See [Removing stale configurations and alerts from a branch](#removing-stale-configurations-and-alerts-from-a-branch). ## Dismissing alerts @@ -131,7 +141,7 @@ If you dismiss an alert but later realize that you need to fix the alert, you ca ## Removing stale configurations and alerts from a branch -You may have multiple code scanning configurations on a single repository. When run, multiple configurations can generate the same alert. Additionally, if the configurations are run on different schedules, the alert statuses may become out-of-date for infrequent or stale configurations. For more information on alerts from multiple configurations, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alerts-from-multiple-configurations). +You may have multiple {% data variables.product.prodname_code_scanning %} configurations on a single repository. When run, multiple configurations can generate the same alert. Additionally, if the configurations are run on different schedules, the alert statuses may become out-of-date for infrequent or stale configurations. For more information on alerts from multiple configurations, see [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/about-code-scanning-alerts#about-alerts-from-multiple-configurations). {% data reusables.repositories.navigate-to-repo %} {% data reusables.repositories.sidebar-security %} diff --git a/content/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign.md b/content/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign.md index 102d8ee6493e..163af82474d4 100644 --- a/content/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign.md +++ b/content/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign.md @@ -30,6 +30,8 @@ This view shows the alerts in the current repository for a campaign called "SQL If you want to see the code that triggered the security alert and the suggested fix, click on the alert name to show the alert view. +{% ifversion copilot %}If {% data variables.copilot.copilot_cloud_agent %} is available in the repository, the fastest way to resolve alerts is to assign them to {% data variables.product.prodname_copilot_short %}, which explores the codebase, generates a fix, validates it, and opens a pull request for you. See [Assigning alerts to {% data variables.copilot.copilot_cloud_agent %}](#assigning-alerts-to-copilot-cloud-agent) below. The following steps describe how to fix alerts yourself instead.{% endif %} + 1. When you are ready to work on one or more security alerts, check that no one else is working on those alerts already. In the campaign view, git icons are displayed on alerts where a fix may already be in progress. Click an icon to display the linked work: * {% octicon "git-pull-request-draft" aria-hidden="Draft pull request" aria-label="git-pull-request-draft" %} an open draft pull request may fix this alert. * {% octicon "git-pull-request" aria-label="Pull request" %} an open pull request may fix this alert. @@ -44,20 +46,18 @@ If you want to see the code that triggered the security alert and the suggested > [!TIP] If you have write permission for more than one repository in the campaign, click the link in the "Campaign progress" box in your repository to show the organization-level view of the campaign. When you open a repository from this view, the campaign alerts view is displayed. -{% ifversion security-campaigns-assign-to-cca %} +{% ifversion copilot %} ## Assigning alerts to {% data variables.copilot.copilot_cloud_agent %} >[!NOTE] This option is currently in public preview and is subject to change. {% data variables.copilot.copilot_cloud_agent %} must be available in the repository. -If an autofix has been generated, you can assign one or more alerts to {% data variables.product.prodname_copilot_short %}. {% data variables.product.prodname_copilot_short %} will create pull requests, apply the autofixes, and add you as a requested reviewer. - -By assigning multiple alerts, {% data variables.copilot.copilot_cloud_agent %} will apply the fixes and iterate on the code to validate the changes, check for any new security issues, and ensure there are no merge conflicts. +Instead of fixing alerts yourself, you can select one or more alerts (up to 25) in the campaign view and assign them to {% data variables.product.prodname_copilot_short %}, which resolves the selected alerts in a single pull request and adds you as a requested reviewer. This is the same assignment flow used to fix an individual alert. See [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts#fixing-alerts-with-copilot). 1. In the campaign view for the repository, select the alerts that you want to assign. -1. Above the list of alerts, click **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} Assign to Copilot**. +1. Above the list of alerts, click **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} Assign to {% data variables.product.prodname_copilot_short %}**. -Within 30 seconds, {% data variables.product.prodname_copilot_short %} will open a pull request to address the security vulnerabilities assigned to {% data variables.product.prodname_copilot_short %} and yourself. The pull request will include a summary of the fixes and details of the changes made. Once created, the pull request is shown next to the alert. +Typically within a few minutes, {% data variables.product.prodname_copilot_short %} opens a pull request addressing the assigned alerts, with a summary of the fixes and the changes made. Once created, the pull request is shown next to the alert. {% endif %} diff --git a/content/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/configure-global-settings.md b/content/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/configure-global-settings.md index 268e155fddb7..1db1a2d63ee6 100644 --- a/content/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/configure-global-settings.md +++ b/content/code-security/how-tos/secure-at-scale/configure-organization-security/establish-complete-coverage/configure-global-settings.md @@ -102,8 +102,13 @@ You can recommend that repositories in your organization use the "Extended" quer You can customize several {% data variables.product.prodname_global_settings %} for {% data variables.product.prodname_code_scanning %}: -{% ifversion code-scanning-autofix %}* [Enabling {% data variables.copilot.copilot_autofix_short %} for {% data variables.product.prodname_codeql %}](#enabling-copilot-autofix-for-codeql){% endif %} * [Recommending the extended query suite for default setup](#recommending-the-extended-query-suite-for-default-setup) +{%- ifversion code-scanning-autofix %} +* [Enabling {% data variables.copilot.copilot_autofix_short %} for {% data variables.product.prodname_codeql %}](#enabling-copilot-autofix-for-codeql) +{%- endif %} +{%- ifversion ai-powered-security-detections %} +* [Enabling AI-powered security detections](#enabling-ai-powered-security-detections) +{%- endif %} * [Expanding {% data variables.product.prodname_codeql %} analysis](#expanding-codeql-analysis) {%- ifversion code-scanning-inactive-repos %} * [Continuing scans on inactive repositories](#continuing-scans-on-inactive-repositories) @@ -123,6 +128,14 @@ You can select **{% data variables.copilot.copilot_autofix_short %}** to enable {% endif %} +{% ifversion ai-powered-security-detections %} + +### Enabling AI-powered security detections + +You can select **AI-powered security detections** to enable AI-powered security detections for all repositories in your organization that use {% data variables.product.prodname_codeql %} default setup. See [AUTOTITLE](/code-security/concepts/code-scanning/ai-powered-security-detections). + +{% endif %} + ### Expanding {% data variables.product.prodname_codeql %} analysis You can expand {% data variables.product.prodname_codeql %} analysis coverage for all repositories in your organization that use default setup by configuring {% data variables.product.prodname_codeql %} model packs. Model packs extend the {% data variables.product.prodname_codeql %} analysis to recognize additional frameworks and libraries that are not included in the standard {% data variables.product.prodname_codeql %} libraries. This global configuration applies to repositories using default setup and allows you to specify model packs published via the container registry. For more information, see [AUTOTITLE](/code-security/how-tos/scan-code-for-vulnerabilities/manage-your-configuration/editing-your-configuration-of-default-setup#extending-coverage-for-all-repositories-in-an-organization). diff --git a/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality.md b/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality.md index 68f8b2873c0e..9d85135722e0 100644 --- a/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality.md +++ b/content/code-security/how-tos/view-and-interpret-data/analyze-organization-data/explore-code-quality.md @@ -30,7 +30,7 @@ category: The score distribution chart provides a visual overview of the code health of your organization. Each bubble represents a collection of repositories with the same maintainability and reliability scores. * The **position** of each bubble demonstrates the overall health of those repositories. Higher bubbles represent higher maintainability scores, while bubbles further to the right represent higher reliability scores. -* The **color and border pattern** of a bubble indicate the severity of the lower score for those repositories. For example, a bubble with a "Needs improvement" score in either category will always be red with a dashed border. +* The **color and border pattern** of a bubble indicate the severity of the lower score for those repositories. For example, a bubble with a "Poor" score in either category will always be red with a dashed border. * The **size** of each bubble represents the number of repositories with that particular score combination. To view the maintainability score, reliability score, and number of repositories represented by a particular bubble, hover over the bubble. diff --git a/content/code-security/reference/code-quality/metrics-and-ratings.md b/content/code-security/reference/code-quality/metrics-and-ratings.md index 1b57b1580859..bd4a5ae9009e 100644 --- a/content/code-security/reference/code-quality/metrics-and-ratings.md +++ b/content/code-security/reference/code-quality/metrics-and-ratings.md @@ -45,7 +45,7 @@ These ratings are used to summarize the overall reliability and maintainability | **Excellent** | Codebase demonstrates best practices for reliability and maintainability. | No code quality findings detected | | **Good** | Codebase has low-severity issues or minor improvements are suggested. | ≥1 "Note" level finding | | **Fair** | Codebase has moderate-severity issues that may impact quality, but are not critical. | ≥1 "Warning" level finding | -| **Needs Improvement**| Codebase has high-severity issues, including bugs or major maintainability risks. | ≥1 "Error" level finding | +| **Poor** | Codebase has high-severity issues, including bugs or major maintainability risks. | ≥1 "Error" level finding | ## Code coverage diff --git a/content/code-security/tutorials/improve-code-quality/improve-your-codebase.md b/content/code-security/tutorials/improve-code-quality/improve-your-codebase.md index 3fed3fe772d1..6237e9adf71e 100644 --- a/content/code-security/tutorials/improve-code-quality/improve-your-codebase.md +++ b/content/code-security/tutorials/improve-code-quality/improve-your-codebase.md @@ -49,7 +49,7 @@ Use the dashboard **filters** to focus on the highest-severity results first ("E To improve your repository's maintainability or reliability rating, you must resolve (fix or dismiss) all findings with the highest severity level for that metric. -For example, to improve your repository's "Reliability" metric from **Needs improvement** to **Fair**, you would need to address and resolve all **error-level findings** that impact reliability. If you have one or more error-level findings, your rating cannot be higher than "Needs improvement". See [AUTOTITLE](/code-security/code-quality/reference/metrics-and-ratings). +For example, to improve your repository's "Reliability" metric from **Poor** to **Fair**, you would need to address and resolve all **error-level findings** that impact reliability. If you have one or more error-level findings, your rating cannot be higher than "Poor". See [AUTOTITLE](/code-security/code-quality/reference/metrics-and-ratings). ## 3. Investigate a group of findings and understand context diff --git a/content/code-security/tutorials/manage-security-alerts/best-practices-for-participating-in-a-security-campaign.md b/content/code-security/tutorials/manage-security-alerts/best-practices-for-participating-in-a-security-campaign.md index 65086004dfd6..07bb39fdef5a 100644 --- a/content/code-security/tutorials/manage-security-alerts/best-practices-for-participating-in-a-security-campaign.md +++ b/content/code-security/tutorials/manage-security-alerts/best-practices-for-participating-in-a-security-campaign.md @@ -26,8 +26,8 @@ In addition to reducing risk in your organization’s codebase, alerts in a secu * You have a campaign manager on the security team to collaborate with and a specific contact link for discussing campaign activities. * You know that you are fixing a security alert that is important to the company. -* Potentially, you may have access to targeted training materials.{% ifversion security-campaigns-autofix %} -* You don't need to request a {% data variables.copilot.copilot_autofix %} suggestion, it is already available as a starting point.{% endif %}{% ifversion copilot %} +* Potentially, you may have access to targeted training materials.{% ifversion copilot %} +* If {% data variables.copilot.copilot_cloud_agent %} is available, you can assign alerts to {% data variables.product.prodname_copilot_short %} and it resolves them for you in a pull request. Otherwise, a {% data variables.copilot.copilot_autofix %} suggestion is already available as a starting point. * If you have access to {% data variables.copilot.copilot_chat %}, you can ask questions about the alert and the suggested fix.{% endif %} * You are improving and demonstrating your knowledge of secure coding. @@ -94,22 +94,14 @@ You can leverage {% data variables.product.prodname_copilot_short %} to help res {% ifversion code-scanning-autofix %} -### {% data variables.copilot.copilot_autofix_short %} +### Autofix for {% data variables.product.prodname_code_scanning %} alerts -{% data variables.copilot.copilot_autofix_short %} is automatically triggered for alerts that are included in a campaign, meaning that where possible, fixes are automatically generated for you. You can commit the suggested fix to resolve the alert and then verify that continuous integration testing (CI) for the codebase is still passing. See [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign). +If {% data variables.copilot.copilot_cloud_agent %} is enabled in the repository, you can select one or more alerts in the campaign view and assign them to {% data variables.product.prodname_copilot_short %}. {% data variables.copilot.copilot_cloud_agent %} explores the codebase, generates fixes, validates the changes, and opens a single pull request for the selected alerts. See [AUTOTITLE](/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign#assigning-alerts-to-copilot-cloud-agent). -{% ifversion security-campaigns-assign-to-cca %} - -If {% data variables.copilot.copilot_cloud_agent %} is enabled in the repository, you can also assign alerts to {% data variables.product.prodname_copilot_short %}. See [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign#assigning-alerts-to-copilot-cloud-agent). - -By assigning multiple alerts, {% data variables.copilot.copilot_cloud_agent %} will apply the fixes and iterate on the code to validate the changes, check for any new security issues, and ensure there are no merge conflicts. - -{% endif %} +If {% data variables.copilot.copilot_cloud_agent %} isn't enabled in the repository, {% data variables.copilot.copilot_autofix_short %} is automatically triggered for alerts included in a campaign, so a fix is generated for you where possible. Commit the suggested fix to resolve the alert, then verify that CI is still passing. See [AUTOTITLE](/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign).{% endif %} ### {% data variables.copilot.copilot_chat_short %} -{% endif %} - You can ask {% data variables.copilot.copilot_chat_short %} for help in understanding the vulnerability, the suggested fix, and how to test that the fix is comprehensive. To access {% data variables.copilot.copilot_chat_short %}, navigate to [https://github.com/copilot](https://github.com/copilot?ref_product=copilot&ref_type=engagement&ref_style=text). Alternatively, when viewing a specific alert, in the top right corner of the page, click the {% data variables.copilot.copilot_chat_short %} icon ({% octicon "copilot" aria-hidden="true" aria-label="copilot" %}) to open a chat window, and ask {% data variables.product.prodname_copilot_short %} questions about the alert. @@ -128,4 +120,4 @@ If you don't already have access to {% data variables.copilot.copilot_chat_short ## Next steps -* [AUTOTITLE](/code-security/code-scanning/managing-code-scanning-alerts/fixing-alerts-in-security-campaign) +* [AUTOTITLE](/code-security/how-tos/manage-security-alerts/remediate-alerts-at-scale/fixing-alerts-in-security-campaign) diff --git a/content/copilot/concepts/context/mcp.md b/content/copilot/concepts/context/mcp.md index 99d9b247dcf9..668806344537 100644 --- a/content/copilot/concepts/context/mcp.md +++ b/content/copilot/concepts/context/mcp.md @@ -34,7 +34,7 @@ category: ## Overview of Model Context Protocol (MCP) -The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). MCP provides a standardized way to connect AI models to different data sources and tools, enabling them to work together more effectively. +{% data reusables.copilot.mcp.intro %} You can use MCP to extend the capabilities of {% data variables.product.prodname_copilot %} by integrating it with a wide range of existing tools and services. MCP works across all major {% data variables.product.prodname_copilot_short %} surfaces—whether you're working in an IDE, using {% data variables.copilot.copilot_cli %}, working in the {% data variables.copilot.github_copilot_app %}, or delegating tasks to an agent on {% data variables.product.prodname_dotcom_the_website %}. You can also use MCP to create new tools and services that work with {% data variables.product.prodname_copilot_short %}, allowing you to customize and enhance your experience. @@ -102,6 +102,12 @@ The {% data variables.product.github %} MCP Registry is a curated list of MCP se >[!NOTE] > The {% data variables.product.github %} MCP Registry is currently in {% data variables.release-phases.public_preview %} and subject to change. +## Agent finder + +Agent finder is a discovery service that helps {% data variables.product.prodname_copilot %} find the right capabilities—such as MCP servers, tools, agents, and skills—for a task at runtime, instead of requiring every capability to be configured in advance. Like an MCP registry, it searches a catalog of capabilities and returns ranked matches that {% data variables.product.prodname_copilot %} can use on demand. Agent finder implements the open Agentic Resource Discovery (ARD) specification. + +To use agent finder, download the [agent finder skill](https://github.com/ards-project/connectors/blob/main/skills/github-copilot/SKILL.md) and add it to your `~/.copilot/skills` directory. For more information about agent skills, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills). To browse the catalog, see [GitHub Agent Finder](https://github.com/agentfinder). + ## Next steps * [AUTOTITLE](/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp)—Add MCP servers to {% data variables.copilot.copilot_chat_short %} in your IDE diff --git a/content/copilot/concepts/mcp-management.md b/content/copilot/concepts/mcp-management.md index 319a384ffec0..327b741197c8 100644 --- a/content/copilot/concepts/mcp-management.md +++ b/content/copilot/concepts/mcp-management.md @@ -10,7 +10,19 @@ category: - Manage Copilot for a team --- -You can manage Model Context Protocol (MCP) server usage in your organization or enterprise by configuring a series of MCP policies on {% data variables.product.prodname_dotcom_the_website %}. Through these policies, you can allow or block MCP server usage entirely, or restrict access to a list of servers that you define in an MCP registry. These policies apply to supported IDEs and {% data variables.copilot.copilot_cli_short %}. +{% data reusables.copilot.mcp.intro %} + +You can manage MCP server usage in your organization or enterprise by configuring a series of MCP policies on {% data variables.product.github %}. Through these policies, you can allow or block MCP server usage entirely, or restrict access to a list of servers that you define in an MCP registry. + +## MCP policy settings + +The following settings let you control how MCP servers are discovered and accessed in your organization or enterprise: + +* **MCP servers in {% data variables.product.prodname_copilot_short %}**: Manage the use of MCP servers for all users with {% data variables.product.prodname_copilot_short %} seats in your organization or enterprise. +* **MCP Registry URL**: Specify the URL of your MCP registry, allowing your developers to discover and use approved MCP servers in supported surfaces. +* **Restrict MCP access to registry servers**: Choose whether to allow all MCP servers or restrict access to only those listed in your configured registry. + +For an overview of which policies apply to which surfaces, see [AUTOTITLE](/copilot/reference/supported-surfaces-for-policies). ## MCP registries @@ -21,23 +33,11 @@ After you create your MCP registry, you can make it available to your company, a * Restrict access to unapproved servers for increased security and compliance * Provide clarity to developers when a server is blocked by policy -## Agent finder - -Agent finder is a discovery service that helps {% data variables.product.prodname_copilot %} find the right capabilities—such as MCP servers, tools, agents, and skills—for a task at runtime, instead of requiring every capability to be configured in advance. Like an MCP registry, it searches a catalog of capabilities and returns ranked matches that {% data variables.product.prodname_copilot %} can use on demand. Agent finder implements the open Agentic Resource Discovery (ARD) specification. - -To use agent finder, download the [agent finder skill](https://github.com/ards-project/connectors/blob/main/skills/github-copilot/SKILL.md) and add it to your `~/.copilot/skills` directory. For more information about agent skills, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills). To browse the catalog, see [GitHub Agent Finder](https://github.com/agentfinder). - -## MCP policy settings - -The following settings let you control how MCP servers are discovered and accessed in your organization or enterprise: - -* **MCP servers in {% data variables.product.prodname_copilot_short %}**: Manage the use of MCP servers for all users with {% data variables.product.prodname_copilot_short %} seats in your organization or enterprise. -* **MCP Registry URL**: Specify the URL of your MCP registry, allowing your developers to discover and use approved MCP servers in supported surfaces. -* **Restrict MCP access to registry servers**: Choose whether to allow all MCP servers or restrict access to only those listed in your configured registry. +To create your own MCP registry, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry). -## Supported surfaces +### Supported surfaces -MCP management features are supported as follows: +The following table lists where MCP registry features are supported in detail. | Surface | Registry display | Allowlist enforcement | |---|:---:|:---:| @@ -51,7 +51,3 @@ MCP management features are supported as follows: > [!NOTE] > For Eclipse, JetBrains, and Xcode, MCP management features are supported in the pre-release versions of {% data variables.product.prodname_copilot_short %}. - -## Next steps - -To create your own MCP registry, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-mcp-usage/configure-mcp-registry). diff --git a/content/copilot/get-started/enterprise-ai-governance.md b/content/copilot/get-started/enterprise-ai-governance.md index 807bc089c776..c7f9c7ac9a31 100644 --- a/content/copilot/get-started/enterprise-ai-governance.md +++ b/content/copilot/get-started/enterprise-ai-governance.md @@ -25,19 +25,28 @@ journeyTracks: - href: '/copilot/concepts/policies' - href: '/copilot/tutorials/roll-out-at-scale/govern-at-scale/maintain-codebase-standards' - href: '/copilot/how-tos/administer-copilot/manage-for-enterprise/review-audit-logs' - - href: '/copilot/concepts/preparing-for-new-features-and-models' - - href: '/copilot/tutorials/roll-out-at-scale/govern-at-scale/pilot-a-feature-or-model' - id: 'adopting_agents' - title: 'Adopting agents' - description: 'Roll out agentic features within secure guardrails.' + title: 'Preparing for agents' + description: 'Learn what agents can do for your enterprise, and prepare to roll them out.' guides: - href: '/copilot/tutorials/roll-out-at-scale/enable-developers/integrate-ai-agents' - href: '/copilot/concepts/agents/enterprise-management' - href: '/copilot/tutorials/cloud-agent/build-guardrails' + - href: '/copilot/concepts/mcp-management' + - id: 'enable_agents' + title: 'Enabling agents' + description: 'Roll out and monitor agentic features.' + guides: - href: '/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent' - href: '/copilot/tutorials/cloud-agent/give-access-to-resources' - href: '/copilot/how-tos/copilot-cli/administer-copilot-cli-for-your-enterprise' - href: '/copilot/tutorials/copilot-cli-hooks' - href: '/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-code-review' - href: '/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/monitor-agentic-activity' + - id: 'new_features' + title: 'Adopting new features' + description: 'Expand your capabilities by assessing and rolling out any new feature or model.' + guides: + - href: '/copilot/concepts/preparing-for-new-features-and-models' + - href: '/copilot/tutorials/roll-out-at-scale/govern-at-scale/pilot-a-feature-or-model' --- diff --git a/content/copilot/how-tos/copilot-cli/cli-best-practices.md b/content/copilot/how-tos/copilot-cli/cli-best-practices.md index 80286aa49bdc..b6e37d42332c 100644 --- a/content/copilot/how-tos/copilot-cli/cli-best-practices.md +++ b/content/copilot/how-tos/copilot-cli/cli-best-practices.md @@ -27,21 +27,13 @@ This article provides tips for getting the most out of {% data variables.copilot ### Use custom instructions files -{% data variables.copilot.copilot_cli_short %} automatically reads instructions from multiple locations, allowing you to define organization-wide standards and repository-specific conventions. +{% data variables.copilot.copilot_cli_short %} automatically combines applicable user-level, repository, and path-specific instructions. Use repository instructions for project conventions and user-level instructions for preferences that should apply across projects. -**Supported locations (in order of discovery):** - -| Location | Scope | -|---------------------------------------------|-----------------------| -| `~/.copilot/copilot-instructions.md` | All sessions (global) | -| `.github/copilot-instructions.md` | Repository | -| `.github/instructions/**/*.instructions.md` | Repository (modular) | -| `AGENTS.md` (in Git root or cwd) | Repository | -| `{% data variables.product.prodname_copilot_short %}.md`, `GEMINI.md`, `CODEX.md` | Repository | +For the complete list of supported locations and details about discovery, file references, and how multiple instruction files interact, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions). #### Best practice -Repository instructions **always take precedence** over global instructions. Use this to enforce team conventions. For example, this is a simple `.github/copilot-instructions.md` file. +Avoid conflicting instructions. For example, this is a simple `.github/copilot-instructions.md` file. ```markdown ## Build Commands diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions.md index 109749eb2644..dc6f2c08e1c2 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions.md @@ -19,43 +19,30 @@ docsTeamMetrics: ## Types of custom instructions -{% data variables.copilot.copilot_cli %} supports the following types of custom instructions. +{% data variables.copilot.copilot_cli %} supports instructions from the following locations. -### Repository-wide custom instructions +Unless noted in the table below, {% data variables.copilot.copilot_cli_short %} discovers repository and agent instruction files in the **standard locations**: the repository root, the current working directory, intermediate directories between them, and any directories nested in the path of a file it is working on. Modular instruction files (those matching `*.instructions.md`) are path-specific—a file with an `applyTo` value applies only to matching files. -These apply to all requests made in the context of a repository. +| Location | Scope and behavior | +| --- | --- | +| `$HOME/.copilot/copilot-instructions.md` | User-level instructions that apply across repositories. | +| `$HOME/.copilot/instructions/**/*.instructions.md` | Modular user-level instructions. | +| `.github/copilot-instructions.md` | Repository-wide instructions, discovered in the standard locations. | +| `.github/instructions/**/*.instructions.md` | Modular repository instructions, discovered in the standard locations but not intermediate directories. | +| `AGENTS.md` | Agent instructions, discovered in the standard locations. For more information, see the [agentsmd/agents.md repository](https://github.com/agentsmd/agents.md). | +| `CLAUDE.md` | Agent instructions, discovered in the standard locations. {% data variables.copilot.copilot_cli_short %} also uses `.claude/CLAUDE.md`. | +| `GEMINI.md` | Agent instructions, discovered in the standard locations. | +| Directories listed in `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` | Additional `AGENTS.md` and `*.instructions.md` files. Separate multiple directories with commas. | -These are specified in a `copilot-instructions.md` file in the `.github` directory at the root of the repository. See [Creating repository-wide custom instructions](#creating-repository-wide-custom-instructions). +If you set the `COPILOT_HOME` environment variable, {% data variables.copilot.copilot_cli_short %} uses that directory instead of `$HOME/.copilot` for both user-level instruction locations. -### Path-specific custom instructions +Use the `/instructions` command to view the instruction files discovered for the current session and enable or disable individual files. -These apply to requests made in the context of files that match a specified path. +## How multiple instruction files interact -These are specified in one or more `NAME.instructions.md` files within or below the `.github/instructions` directory at the root of the repository, or within or below a `.github/instructions` directory in the current working directory. See [Creating path-specific custom instructions](#creating-path-specific-custom-instructions). +When multiple applicable user-level and repository instruction files exist, {% data variables.copilot.copilot_cli_short %} combines their instructions. It removes duplicate copies of identical user-level `copilot-instructions.md`, repository-wide, and agent instructions, but does not define a general precedence order between these files. Avoid conflicting instructions. -If the path you specify in these instructions matches a file that {% data variables.product.prodname_copilot_short %} is working on, and a repository-wide custom instructions file also exists, then the instructions from both files are used. You should avoid potential conflicts between instructions as {% data variables.product.prodname_copilot_short %}'s choice between conflicting instructions is non-deterministic. - -### Agent instructions - -These are used by various AI agents. - -You can create one or more `AGENTS.md` files. These can be located in the repository's root directory, in the current working directory, or in any of the directories specified by a comma-separated list of paths in the `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` environment variable. - -Instructions in the `AGENTS.md` file in the root directory, if found, are treated as primary instructions. If an `AGENTS.md` file and a `.github/copilot-instructions.md` file are both found at the root of the repository, the instructions in both files are used. - -Instructions found in other `AGENTS.md` files are treated as additional instructions. Any primary instructions that are found are likely to have more effect on {% data variables.product.prodname_copilot_short %}'s responses than additional instructions. - -For more information, see the [agentsmd/agents.md repository](https://github.com/agentsmd/agents.md). - -Alternatively, you can use `CLAUDE.md` and `GEMINI.md` files. These must be located at the root of the repository. - -### Local instructions - -These apply within a specific local environment. - -You can specify instructions within your own home directory, by creating a file at `$HOME/.copilot/copilot-instructions.md`. - -You can also set the `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` environment variable to a comma-separated list of directories. {% data variables.copilot.copilot_cli_short %} will look for an `AGENTS.md` file, and any `.github/instructions/**/*.instructions.md` files, in each of these directories. +Path-specific instructions are included only when their `applyTo` value matches a file that {% data variables.copilot.copilot_cli_short %} is working with. An instruction file that you disable using `/instructions` is not included. ## Creating repository-wide custom instructions @@ -69,6 +56,12 @@ You can also set the `COPILOT_CUSTOM_INSTRUCTIONS_DIRS` environment variable to For help on writing effective custom instructions, see [AUTOTITLE](/copilot/concepts/prompting/response-customization#writing-effective-custom-instructions). +### Referencing other files + +In `.github/copilot-instructions.md`, `AGENTS.md`, or `CLAUDE.md`, use `@` followed by a relative path to include another file. {% data variables.copilot.copilot_cli_short %} reads the referenced file immediately and supports references within referenced files. + +Referenced files must remain within the repository, or within the custom instructions directory for local instructions. Absolute paths and paths beginning with `~/` are not loaded. File references are not expanded in `GEMINI.md` or `*.instructions.md` files. + ## Creating path-specific custom instructions {% data reusables.copilot.custom-instructions-path %} diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md index 1899ed77857a..15ee96de7f70 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli/allowing-tools.md @@ -24,7 +24,11 @@ You can allow or deny permissions for tools either when you start the CLI or dur ## Persisted permissions -If you answer "yes, always" or otherwise choose the option to allow similar requests for the current location, the approval is saved to `permissions-config.json` in your configuration directory (by default, `~/.copilot/permissions-config.json`). +Some prompt options save your consent so you aren't asked again. Where your approval is stored depends on what you approved. + +When you approve a tool for the current location, the approval is saved to `permissions-config.json` in your configuration directory. By default, this file is `~/.copilot/permissions-config.json`. For example, you might choose "don't ask again in this repo" (or "in this directory") for a shell command, file write, MCP tool, or memory update. The approval is scoped to the current location: either the Git repository root, or the working directory if you aren't in a repository. Any directories you grant access to are saved to the same file. + +URL approvals work differently. When you approve a URL permanently, its domain is added to the `allowedUrls` list in your `settings.json`. By default, this file is `~/.copilot/settings.json`. This approval applies across all your sessions, rather than being tied to a single location. Command-line options such as `--allow-tool` and `--deny-tool` apply only to the current session and aren't written to `permissions-config.json`. Deny rules still take precedence over saved approvals. diff --git a/content/copilot/reference/copilot-cli-reference/acp-server.md b/content/copilot/reference/copilot-cli-reference/acp-server.md index f5c190bda12c..66b7b6f89041 100644 --- a/content/copilot/reference/copilot-cli-reference/acp-server.md +++ b/content/copilot/reference/copilot-cli-reference/acp-server.md @@ -30,14 +30,29 @@ The Agent Client Protocol (ACP) is a protocol that standardizes communication be ## Starting the ACP server -{% data variables.copilot.copilot_cli %} can be started as an ACP server using the `--acp` flag. The server supports two modes, `stdio` and `TCP`. +Use the `--acp` option of the `copilot` command to start the CLI's ACP server. You can specify the transport mode with either the `--stdio` or `--port` options. If no transport mode is specified, the server defaults to stdio mode. -> [!NOTE] -> When running in ACP mode, the tool-filtering flags (`--available-tools`, `--excluded-tools`) and the reasoning flag (`--effort`, `--reasoning-effort`) are applied to each session started by the ACP client. +### Options applied to every session + +The ACP `session/new` request only lets a client set a few session parameters, such as the working directory and the MCP servers to use. It does not carry tool-filtering or reasoning settings. To configure those, pass the corresponding options when you **start the server**. The server stores the values and applies them as the initial configuration for every session it creates or loads, for any client that connects. A connecting client does not choose these values—whoever launches the server does. -### stdio mode (recommended for IDE integration) +| Server option | Accepted value | Effect on every session | +|---------------|----------------|-------------------------| +| `--available-tools=TOOL ...` | A quoted, comma-separated list of tool names | The session can use only the listed tools. | +| `--excluded-tools=TOOL ...` | A quoted, comma-separated list of tool names | The listed tools are removed from the session. | +| `--effort=LEVEL`, `--reasoning-effort=LEVEL` | `low`, `medium`, `high`, `xhigh`, or `max` | Sets the session's initial reasoning effort. | -By default, when providing the `--acp` flag, `stdio` mode will be inferred. The `--stdio` flag can also be provided for disambiguation. +For example, this command starts a server whose sessions all use maximum reasoning effort and expose only the `bash` and `view` tools: + +```bash +copilot --acp --port 3000 --effort=max --available-tools="bash,view" +``` + +Every session the connected client opens against that server inherits those settings. Because the values are fixed when the server starts, a client cannot change them per session through `session/new`. + +### stdio mode + +stdio mode is inferred by default when you start the ACP server. You can also use the `--stdio` option for disambiguation. ```bash copilot --acp --stdio @@ -45,20 +60,45 @@ copilot --acp --stdio ### TCP mode -If the `--port` flag is provided in combination with the `--acp` flag, the server is started in TCP mode. +If the `--port` option is provided in combination with the `--acp` option, the server is started in TCP mode. ```bash copilot --acp --port 3000 ``` -## Integrating with the ACP server +### Choosing between stdio and TCP + +Both transport modes carry the same ACP messages, encoded as newline-delimited JSON (NDJSON). They differ only in how a client connects to the server and how the server's lifecycle is managed. The two modes are mutually exclusive: passing both `--stdio` and `--port` is rejected. + +| Aspect | stdio mode | TCP mode | +|---|---|---| +| **How the client connects** | The client launches `copilot --acp` as a child process and exchanges messages over the process's standard input and output. | The server opens a TCP listener that clients connect to over a network socket. By default it binds to the loopback address `127.0.0.1`. | +| **Number of clients** | A single client—the process that spawned the server and owns the pipe. | The listener accepts socket connections, each handled as its own agent connection. | +| **Lifecycle** | Tied to the parent process. When the input stream closes—because the parent exits or closes the pipe—the server shuts down automatically. | Independent of any single client. The server keeps listening on the port until it is stopped, for example with Ctrl+C. | +| **Standard output** | Reserved for the NDJSON protocol stream, so it can't be used for logs or other text. | Free for other use, because protocol traffic travels over the socket. | + +When to use each mode: -There is a growing ecosystem of libraries to programmatically interact with ACP servers. Given {% data variables.copilot.copilot_cli %} is correctly installed and authenticated, the following example demonstrates using the [typescript](https://agentclientprotocol.com/libraries/typescript) client to send a single prompt and print the AI response. +* Use **stdio mode** when an editor, IDE, or script spawns {% data variables.copilot.copilot_cli_short %} directly as a subprocess. This is the default and the recommended setup for IDE integration, because the transport is established automatically when the process starts and torn down when it exits. +* Use **TCP mode** when a client needs to reach the server over a socket instead of a pipe—for example, from a separate process or container, or when connecting to a longer-lived server on a known port. -```typescript +## Example: integrating with the ACP server + +The following example is a client application that uses {% data variables.product.prodname_copilot_short %} by interacting with {% data variables.copilot.copilot_cli %}'s ACP server. It starts the ACP server in stdio mode, opens a session, asks you to enter a prompt, sends it, and prints the streamed response. + +There is a growing ecosystem of libraries for interacting with ACP servers programmatically. This example uses the [ACP TypeScript library](https://agentclientprotocol.com/libraries/typescript). + +To run this example, you need the following dependencies: + +* [Node.js](https://nodejs.org) version 18 or later. +* {% data variables.copilot.copilot_cli %}, installed and authenticated. +* The `@agentclientprotocol/sdk` package, which provides the ACP TypeScript library. Install it by running `npm install @agentclientprotocol/sdk`. + +```typescript copy import * as acp from "@agentclientprotocol/sdk"; import { spawn } from "node:child_process"; import { Readable, Writable } from "node:stream"; +import * as readline from "node:readline/promises"; async function main() { const executable = process.env.COPILOT_CLI_PATH ?? "copilot"; @@ -105,8 +145,14 @@ async function main() { }); process.stdout.write("Session started!\n"); - const promptText = "Hello ACP Server!"; - process.stdout.write(`Sending prompt: '${promptText}'\n`); + + // Ask the user to enter a prompt instead of using a hard-coded one. + const rl = readline.createInterface({ + input: process.stdin, + output: process.stdout, + }); + const promptText = await rl.question("Enter a prompt: "); + rl.close(); const promptResult = await connection.prompt({ sessionId: sessionResult.sessionId, @@ -134,7 +180,71 @@ main().catch((error) => { }); ``` +To run the example: + +1. Save the code above to a file named `acp-client.ts`. +1. Run the file with `npx tsx`, which runs the TypeScript directly without a separate build step: + + ```bash + npx tsx acp-client.ts + ``` + +## Using slash commands + +{% data variables.copilot.copilot_cli %}'s built-in slash commands can be run over ACP. To invoke one, send it as an ordinary prompt whose text is the command, passed as a single text content block—for example, `/context` or `/session info`. The server recognizes the command and runs it directly: informational commands such as `/usage` or `/context` return their output without invoking the model, while action commands such as `/plan` or `/review` start the corresponding agent task. Either way, the command text is not sent to the model as a question. + +### Discovering available commands + +The server advertises the commands it supports through the standard ACP `available_commands_update` session notification. It is sent after a session is created or loaded, and again whenever the set changes—for example, when skills finish loading. This advertised list is the authoritative, always-current set of commands you can run over ACP, and clients typically surface it in a command menu. + +The advertised list contains: + +* **Built-in commands**, such as `/compact`, `/context`, `/usage`, `/env`, `/model`, `/mcp`, `/plan`, `/review`, `/research`, `/session`, and `/rename`. +* **Enabled, user-invocable skills**, which appear as `/SKILL-NAME` commands. + +Commands that the client itself registers are not advertised back to it. + +### Accessing the list from your client + +Because the list arrives as a notification rather than in response to a request, there is no method to fetch it on demand. Your client accesses it by handling the `session/update` notification and reacting to updates whose type is `available_commands_update`. Each entry has a `name` (without the leading slash), a `description`, and an optional `input.hint` that describes the command's arguments. The notification is re-sent whenever the set changes, so treat each one as a complete replacement of any list you have cached. + +The following `sessionUpdate` handler captures the advertised commands, extending the `client` object from the example shown earlier. + +```typescript copy +// Track the latest advertised commands for the session. +let availableCommands: acp.AvailableCommand[] = []; + +const client: acp.Client = { + async sessionUpdate(params) { + const update = params.update; + + if (update.sessionUpdate === "available_commands_update") { + // This notification is a full snapshot—replace any cached list. + availableCommands = update.availableCommands; + for (const command of availableCommands) { + // command.name has no leading slash; invoke it by sending "/" as a prompt. + console.log(`/${command.name} — ${command.description}`); + } + return; + } + + // ...handle other updates, such as agent_message_chunk + }, + + // ...other client methods, such as requestPermission +}; +``` + +To run one of the advertised commands, send its name as a prompt in a single text content block—for example, `{ type: "text", text: "/context" }`—as described in [Using slash commands](#using-slash-commands). + +### Commands that cannot be used over ACP + +Slash commands that depend on the interactive terminal interface are not handled by the ACP server. This includes commands that open a picker, dialog, or full-screen view, such as `/diff`, `/resume`, `/theme`, `/settings`, `/login`, `/help`, `/tasks`, and `/undo`. As a rule, if a command does not appear in the `available_commands_update` list, it will not run over ACP: the server treats the text as an ordinary prompt and forwards it to the model instead of executing it. + +Because ACP clients have no interactive pickers, a built-in command that would normally open a submenu instead returns its options as text. Provide the subcommand explicitly to get a direct result—for example, `/session info` or `/mcp list` rather than `/session` or `/mcp` on its own. + +For a complete list of slash commands for {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#slash-commands-in-the-interactive-interface). + ## Further reading -* [AUTOTITLE](/copilot/concepts/agents/copilot-in-jetbrains) * [Official ACP documentation](https://agentclientprotocol.com/protocol/overview) diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index c6c8f8e33ba1..dfd36afc4c07 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -193,6 +193,8 @@ When diff mode is open (entered via `/diff`): ## Slash commands in the interactive interface +These are the slash commands you can use from within an interactive CLI session. A subset of these slash commands is available to clients that use the CLI via its ACP server. For more information, see [AUTOTITLE](/copilot/reference/copilot-cli-reference/acp-server). + | Command | Purpose | |-----------------------------------------------------|---------| | `/add-dir PATH` | Add a directory to the allowed list for file access. | diff --git a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md index cf1e4090b0fc..82fd273f5b00 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-config-dir-reference.md @@ -139,6 +139,8 @@ Stores your saved tool and directory permission decisions, organized by project | 2 | `COPILOT_HOME` | `$COPILOT_HOME/permissions-config.json` | | 3 | Default | `~/.copilot/permissions-config.json` | +The CLI uses only the first applicable configuration directory in this order. It doesn't also load `permissions-config.json` from the lower-priority locations. + The `--config-dir` option is a legacy option. Prefer `COPILOT_HOME` when you need to change the configuration directory. On Windows, the default file is typically: @@ -206,7 +208,7 @@ For MCP approvals, `serverName` must match the configured MCP server name exactl #### Shell command matching -`commandIdentifiers` match the command identifiers extracted from a shell request. Matching is exact except for the `:*` suffix. +`permissions-config.json` doesn't support regular expressions or general glob patterns. String values are matched literally, except that a trailing `:*` in a shell `commandIdentifiers` value matches the text before `:*`, either by itself or followed by a space and more text. A plain `*` has no special meaning, so `git*` doesn't match `git status`. | Pattern | Matches | Doesn't match | |---------|---------|---------------| @@ -214,8 +216,6 @@ For MCP approvals, `serverName` must match the configured MCP server name exactl | `git:*` | `git`, `git status`, `git push` | `gitea` | | `gh pr:*` | `gh pr`, `gh pr view`, `gh pr create` | `gh repo view` | -The `:*` suffix isn't a general glob pattern. It matches the exact stem, or the stem followed by a space and more text. - #### Directory matching `allowed_directories` entries allow {% data variables.copilot.copilot_cli_short %} to access paths inside those directories without a separate path prompt. They don't approve the tool operation itself. For example, editing a file in an allowed directory can still require a `write` approval. diff --git a/content/copilot/reference/custom-instructions-support.md b/content/copilot/reference/custom-instructions-support.md index 0bb28e017b7f..88476f69c24e 100644 --- a/content/copilot/reference/custom-instructions-support.md +++ b/content/copilot/reference/custom-instructions-support.md @@ -264,7 +264,8 @@ The editor lets you work with workspace customizations for the current project o ## Further reading diff --git a/content/get-started/learning-about-github/about-github-advanced-security.md b/content/get-started/learning-about-github/about-github-advanced-security.md index c488bcc02f42..3fdf00d071f0 100644 --- a/content/get-started/learning-about-github/about-github-advanced-security.md +++ b/content/get-started/learning-about-github/about-github-advanced-security.md @@ -34,7 +34,9 @@ You get the following features with {% data variables.product.prodname_GH_code_s * **{% data variables.product.prodname_codeql_cli %}**: Run {% data variables.product.prodname_codeql %} processes locally on software projects or to generate {% data variables.product.prodname_code_scanning %} results for upload to {% data variables.product.github %}.{% ifversion code-scanning-autofix %} -* **{% data variables.copilot.copilot_autofix_short %}**: Get automatically generated fixes for {% data variables.product.prodname_code_scanning %} alerts.{% endif %}{% ifversion security-campaigns %} +* **{% data variables.copilot.copilot_autofix_short %}**: Get automatically generated fixes for {% data variables.product.prodname_code_scanning %} alerts.{% ifversion ai-powered-security-detections %} + +* **AI-powered security detections**: Find vulnerabilities in languages and frameworks not covered by {% data variables.product.prodname_codeql %} with an AI-based scanning engine that runs during pull request review.{% endif %}{% endif %}{% ifversion security-campaigns %} * **Security campaigns**: Reduce security debt at scale.{% endif %} diff --git a/data/features/ai-powered-security-detections.yml b/data/features/ai-powered-security-detections.yml new file mode 100644 index 000000000000..7154b92dd0bf --- /dev/null +++ b/data/features/ai-powered-security-detections.yml @@ -0,0 +1,4 @@ +# Reference: #20824 +versions: + ghec: '*' + fpt: '*' diff --git a/data/reusables/copilot/mcp/intro.md b/data/reusables/copilot/mcp/intro.md new file mode 100644 index 000000000000..3ad5a99128fd --- /dev/null +++ b/data/reusables/copilot/mcp/intro.md @@ -0,0 +1 @@ +The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). MCP provides a standardized way to connect AI models to different data sources and tools, enabling them to work together more effectively. diff --git a/data/reusables/rai/code-scanning/gated-feature-autofix.md b/data/reusables/rai/code-scanning/gated-feature-autofix.md index 3ecec43c52f0..6ef2beb6a700 100644 --- a/data/reusables/rai/code-scanning/gated-feature-autofix.md +++ b/data/reusables/rai/code-scanning/gated-feature-autofix.md @@ -1,4 +1,4 @@ -{% data variables.copilot.copilot_autofix %} for {% data variables.product.prodname_code_scanning %} is available for the following repository types: +{% data variables.copilot.copilot_autofix_short %} for {% data variables.product.prodname_code_scanning %} is available for the following repository types: {% ifversion fpt %} * Public repositories on {% data variables.product.prodname_dotcom_the_website %} @@ -6,4 +6,6 @@ {% ifversion ghec %} * Public repositories on {% data variables.product.prodname_dotcom_the_website %} -* Organization-owned repositories on {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} with [{% data variables.product.prodname_GH_code_security %}](/get-started/learning-about-github/about-github-advanced-security) enabled{% endif %} +* Organization-owned repositories on {% data variables.product.prodname_team %} or {% data variables.product.prodname_ghe_cloud %} with [{% data variables.product.prodname_GH_code_security %}](/get-started/learning-about-github/about-github-advanced-security) enabled{% endif %}
+ +Agentic autofix additionally requires {% data variables.copilot.copilot_cloud_agent %} to be available in the repository.