diff --git a/.github/agents/builder-writer.md b/.github/agents/builder-writer.md index 7d92cfd95e75..b846ea2c8b43 100644 --- a/.github/agents/builder-writer.md +++ b/.github/agents/builder-writer.md @@ -2,6 +2,7 @@ name: "Builder-writer" description: "Use when writing, editing, or reviewing content for the Builder persona: developers building software, from junior to senior and solo to enterprise, who write, review, test, ship, and operate code." +include-custom-instructions: true --- diff --git a/.github/agents/driver-writer.md b/.github/agents/driver-writer.md index 7e65c7a44082..a8bd95a3d6ad 100644 --- a/.github/agents/driver-writer.md +++ b/.github/agents/driver-writer.md @@ -2,6 +2,7 @@ name: "Driver-writer" description: "Use when writing, editing, or reviewing content for the Driver persona: enterprise administrators, platform engineers, billing managers, security leads, and others who enable developers at scale." +include-custom-instructions: true --- diff --git a/.github/instructions/all.instructions.md b/.github/instructions/all.instructions.md index 9651217e785f..dcc43377c460 100644 --- a/.github/instructions/all.instructions.md +++ b/.github/instructions/all.instructions.md @@ -6,6 +6,12 @@ applyTo: "**" This repository powers the GitHub Docs site (docs.github.com). It contains both the Next.js application code (TypeScript) and the documentation content (Markdown). +## Choosing the pull request repository + +- For work by GitHub employees, create pull requests in `github/docs-internal` by default, even if the current clone or `origin` remote points to `github/docs`. Use `github/docs` only when the contribution is intentionally public, such as when collaborating with an external contributor or customer. +- Treat work originating from an internal repository, issue, pull request, or discussion as internal. +- Before pushing a branch or creating a pull request, verify the destination repository explicitly instead of inferring it from the current Git remote. If the intended destination is unclear, ask the user. + ## Creating a pull request When you create a pull request: diff --git a/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png b/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png index 753baed74ec1..c4c332d8a203 100644 Binary files a/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png and b/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-1.png differ diff --git a/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png b/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png index 3060cb1c255f..870e767a59a3 100644 Binary files a/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png and b/assets/images/help/copilot/copilot-sdk/features-agent-loop-diagram-2.png differ diff --git a/assets/images/help/copilot/copilot-sdk/setup-in-process-runtime-diagram-0.png b/assets/images/help/copilot/copilot-sdk/setup-in-process-runtime-diagram-0.png new file mode 100644 index 000000000000..909feda77a0a Binary files /dev/null and b/assets/images/help/copilot/copilot-sdk/setup-in-process-runtime-diagram-0.png differ diff --git a/content/actions/how-tos/reuse-automations/reuse-workflows.md b/content/actions/how-tos/reuse-automations/reuse-workflows.md index 2049cbdef4a0..97dd9dbfa421 100644 --- a/content/actions/how-tos/reuse-automations/reuse-workflows.md +++ b/content/actions/how-tos/reuse-automations/reuse-workflows.md @@ -307,7 +307,7 @@ For more information on using job outputs, see [AUTOTITLE](/actions/reference/wo ## Controlling cache access in reusable workflows -You can use the `cache-mode` key to grant a reusable workflow the least amount of {% data variables.product.prodname_actions %} cache access it needs. The value can be `read`, `write`, `write-only`, or `none`. If you omit `cache-mode`, a `read` or `write` default is used based on the trigger type. For the full syntax and the meaning of each value, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-syntax#cache-mode). For trigger-dependent defaults, see [AUTOTITLE](/actions/reference/dependency-caching-reference#defaults). +You can use the `cache-mode` key to grant a reusable workflow the least amount of {% data variables.product.prodname_actions %} cache access it needs. The value can be `read`, `write`, `write-only`, or `none`. If you omit `cache-mode`, a `read` or `write` default is used based on the trigger type. For the full syntax and the meaning of each value, see [AUTOTITLE](/actions/reference/workflows-and-actions/workflow-syntax#cache-mode). For trigger-dependent defaults, see [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#defaults). When a caller workflow calls a reusable workflow, `cache-mode` propagates to the called workflow. An explicit `cache-mode` on the calling job, or inherited from the caller workflow, limits the cache access the called workflow can request. @@ -315,7 +315,7 @@ If the calling job neither sets nor inherits an explicit `cache-mode`, the calle If a called workflow declares a `cache-mode` that requests access beyond this explicit limit, the run does not start and {% data variables.product.github %} reports a validation error. For example, a caller that allows at most `read` cannot call a workflow that declares `write`. Because `read` grants restore access and `write-only` grants save access, the two are non-overlapping capabilities, so a mismatch between them is also an over-request. For example, a `write-only` caller cannot call a workflow that declares `read`. -For more information about cache access and the four modes, see [AUTOTITLE](/actions/reference/dependency-caching-reference#controlling-cache-access-with-cache-mode). +For more information about cache access and the four modes, see [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#controlling-cache-access-with-cache-mode). {% endif %} diff --git a/content/actions/reference/workflows-and-actions/workflow-syntax.md b/content/actions/reference/workflows-and-actions/workflow-syntax.md index f21517189d49..22fd3cf022c0 100644 --- a/content/actions/reference/workflows-and-actions/workflow-syntax.md +++ b/content/actions/reference/workflows-and-actions/workflow-syntax.md @@ -415,12 +415,12 @@ Access is enforced with scoped cache tokens, so a job cannot restore or save cac | `write-only` | No | Yes | | `none` | No | No | -If you omit `cache-mode`, a `read` or `write` default is used based on the trigger type. For trigger-dependent effective defaults, see [AUTOTITLE](/actions/reference/dependency-caching-reference#defaults). +If you omit `cache-mode`, a `read` or `write` default is used based on the trigger type. For trigger-dependent effective defaults, see [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#defaults). > [!WARNING] -> Explicitly declaring `cache-mode: write` or `cache-mode: write-only` on low-trust triggers can bypass the secure default read-only cache restriction and reintroduce cache-poisoning risk. For guidance and mitigations, see [AUTOTITLE](/actions/reference/dependency-caching-reference#bypassing-the-default-untrusted-trigger-cache-restriction). +> Explicitly declaring `cache-mode: write` or `cache-mode: write-only` on low-trust triggers can bypass the secure default read-only cache restriction and reintroduce cache-poisoning risk. For guidance and mitigations, see [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#bypassing-the-default-untrusted-trigger-cache-restriction). -When a cache operation is not permitted by the effective mode, the cache step logs an informational message and continues. The job and workflow do not fail. A skipped restore is treated as a cache miss; a skipped save is simply not performed. For more information, see [AUTOTITLE](/actions/reference/dependency-caching-reference#controlling-cache-access-with-cache-mode). +When a cache operation is not permitted by the effective mode, the cache step logs an informational message and continues. The job and workflow do not fail. A skipped restore is treated as a cache miss; a skipped save is simply not performed. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#controlling-cache-access-with-cache-mode). ### Example of `cache-mode` @@ -516,10 +516,10 @@ jobs: Use `jobs..cache-mode` to set the level of {% data variables.product.prodname_actions %} cache access for a single job. A value set here overrides any workflow-level [`cache-mode`](#cache-mode) for this job only. -The accepted values are `read`, `write`, `write-only`, and `none`, with the same meanings as the top-level key. If neither the job nor the workflow sets `cache-mode`, a trigger-based default applies. For more information about each value, see [`cache-mode`](#cache-mode) and [AUTOTITLE](/actions/reference/dependency-caching-reference#defaults). +The accepted values are `read`, `write`, `write-only`, and `none`, with the same meanings as the top-level key. If neither the job nor the workflow sets `cache-mode`, a trigger-based default applies. For more information about each value, see [`cache-mode`](#cache-mode) and [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#defaults). > [!WARNING] -> Explicitly declaring `cache-mode: write` or `cache-mode: write-only` on low-trust triggers can bypass the secure default read-only cache restriction and reintroduce cache-poisoning risk. For guidance and mitigations, see [AUTOTITLE](/actions/reference/dependency-caching-reference#bypassing-the-default-untrusted-trigger-cache-restriction). +> Explicitly declaring `cache-mode: write` or `cache-mode: write-only` on low-trust triggers can bypass the secure default read-only cache restriction and reintroduce cache-poisoning risk. For guidance and mitigations, see [AUTOTITLE](/actions/reference/workflows-and-actions/dependency-caching#bypassing-the-default-untrusted-trigger-cache-restriction). You can also set `cache-mode` on a job that calls a reusable workflow to limit the cache access granted to the called workflow. For more information, see [AUTOTITLE](/actions/reference/workflows-and-actions/reusing-workflow-configurations#supported-keywords-for-jobs-that-call-a-reusable-workflow) and [AUTOTITLE](/actions/how-tos/reuse-automations/reuse-workflows#controlling-cache-access-in-reusable-workflows). diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence.md new file mode 100644 index 000000000000..973f50640792 --- /dev/null +++ b/content/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence.md @@ -0,0 +1,52 @@ +--- +title: Configuring Proof of Presence +shortTitle: Proof of Presence +intro: 'Reduce the risk from compromised sessions by requiring people to reauthenticate with your identity provider before they perform high-impact actions in your enterprise.' +product: 'Enterprise accounts on {% data variables.product.prodname_ghe_cloud %}' +versions: + feature: proof-of-presence +contentType: concepts +--- + +{% data reusables.public-preview.public-preview %} + +## About Proof of Presence + +Proof of Presence (PoP) adds an identity-provider challenge to sudo mode for enterprises. When a member attempts a protected high-impact action, {% data variables.product.github %} requires the member to reauthenticate through the enterprise's configured identity provider (IdP) before the action can proceed. + +PoP uses the same session and timeout model as sudo mode, and the same protected actions that trigger sudo mode will trigger a PoP challenge. After a member successfully reauthenticates, the member can perform protected actions until the sudo-mode session expires. See [AUTOTITLE](/authentication/keeping-your-account-and-data-secure/sudo-mode). + +PoP can help you reduce the impact of a compromised session and meet compliance requirements for fresh authentication before sensitive operations. Before enabling PoP, make sure your IdP authentication policies provide the level of assurance that you require. + +## Supported identity providers + +{% data reusables.enterprise-accounts.proof-of-presence-supported-idps %} + +## What members experience + +When a member of your enterprise attempts a protected action and needs to reauthenticate, {% data variables.product.github %} redirects the member to the enterprise's IdP. The member follows the IdP prompts, including any required multi-factor authentication, then returns to {% data variables.product.github %} to complete the action. + +If a member cannot complete the challenge, they should contact the enterprise administrator or IdP administrator who manages authentication for the enterprise. + +## Prerequisites + +Before you use PoP, configure SSO between your enterprise and a supported IdP. The configuration depends on your account and deployment type: + +* For an enterprise that uses personal accounts, see [AUTOTITLE](/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise). +{% ifversion ghec %} +* For an enterprise that uses {% data variables.product.prodname_emus %}, see [AUTOTITLE](/admin/managing-iam/understanding-iam-for-enterprises/getting-started-with-enterprise-managed-users#configure-authentication). +{% endif %} + +## Enabling Proof of Presence + +When you enable Proof of Presence, this policy will apply across your enterprise. + +{% data reusables.enterprise-accounts.access-enterprise %} +{% data reusables.enterprise-accounts.settings-tab %} +1. Under {% octicon "gear" aria-hidden="true" aria-label="gear" %} **Settings**, click **Authentication security**. +1. From the **Proof of presence** dropdown menu, select an authentication requirement. + + Both options require the member to complete an authentication challenge through your IdP. + + * **Re-authentication**: Requires the member to authenticate again. Depending on your enterprise's authentication policy, the member may be able to satisfy the challenge with password-based authentication. + * **MFA**: Requires the member to authenticate again and satisfy an additional multi-factor authentication challenge, such as using an authenticator app or biometric scan, as configured by your enterprise. diff --git a/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md b/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md index 1e237872da2b..2fb021cbaf63 100644 --- a/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md +++ b/content/admin/configuring-settings/hardening-security-for-your-enterprise/index.md @@ -6,6 +6,7 @@ versions: ghec: '*' ghes: '*' children: + - /configuring-proof-of-presence - /configuring-tls - /configuring-tls-and-ssh-ciphers - /troubleshooting-tls-errors diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md index 5788ac682b8b..42f97765af14 100644 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md +++ b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-oidc-for-enterprise-managed-users.md @@ -65,3 +65,7 @@ After you enable OIDC SSO, enable provisioning. See [AUTOTITLE](/admin/managing- You can use the role of guest collaborator to grant limited access to vendors and contractors in your enterprise. Unlike enterprise members, guest collaborators only have access to internal repositories within organizations where they are a member. To use guest collaborators with OIDC authentication, you may need to update your settings in Entra ID. See [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators). + +## Enabling Proof of Presence + +After you configure OIDC SSO, your enterprise can use Proof of Presence to require reauthentication through your IdP before high-impact actions. {% data reusables.enterprise-accounts.proof-of-presence-supported-idps %} For more information, see [AUTOTITLE](/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence). diff --git a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md index 72548185597b..9ce536b66f59 100644 --- a/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md +++ b/content/admin/managing-iam/configuring-authentication-for-enterprise-managed-users/configuring-saml-single-sign-on-for-enterprise-managed-users.md @@ -133,3 +133,7 @@ After you enable SAML SSO, enable provisioning. For more information, see [AUTOT You can use the role of guest collaborator to grant limited access to vendors and contractors in your enterprise. Unlike enterprise members, guest collaborators only have access to internal repositories within organizations where they are a member. If you use Entra ID or Okta for SAML authentication, you may need to update your IdP application to use guest collaborators. For more information, see [AUTOTITLE](/admin/managing-accounts-and-repositories/managing-users-in-your-enterprise/enabling-guest-collaborators). + +### Enable Proof of Presence + +After you configure SAML SSO, your enterprise can use Proof of Presence to require reauthentication through your IdP before high-impact actions. {% data reusables.enterprise-accounts.proof-of-presence-supported-idps %} For more information, see [AUTOTITLE](/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence). diff --git a/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md b/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md index c81e4e87653a..340d6d1c9101 100644 --- a/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md +++ b/content/admin/managing-iam/using-saml-for-enterprise-iam/configuring-saml-single-sign-on-for-your-enterprise.md @@ -148,6 +148,14 @@ You can enable or disable SAML authentication for {% data variables.location.pro {% endif %} +{% ifversion proof-of-presence %} + +## Enabling Proof of Presence + +After you configure SAML SSO, your enterprise can use Proof of Presence to require reauthentication through your IdP before high-impact actions. {% data reusables.enterprise-accounts.proof-of-presence-supported-idps %} For more information, see [AUTOTITLE](/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence). + +{% endif %} + ## Further reading {%- ifversion ghec %} diff --git a/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md b/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md index ae9e35c46628..85c4fde4af48 100644 --- a/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md +++ b/content/authentication/keeping-your-account-and-data-secure/sudo-mode.md @@ -1,6 +1,6 @@ --- title: Sudo mode -intro: 'To confirm access to your account before you perform a potentially sensitive action, {% data variables.location.product_location %} prompts for authentication.' +intro: 'To confirm access to your account before you perform a protected high-impact action, {% data variables.location.product_location %} prompts for authentication.' redirect_from: - /articles/sudo-mode - /github/authenticating-to-github/sudo-mode @@ -15,12 +15,16 @@ category: ## About sudo mode -To maintain the security of your account when you perform a potentially sensitive action on {% data variables.location.product_location %}, you must authenticate even though you're already signed in. For example, {% data variables.product.company_short %} considers the following actions sensitive because each action could allow a new person or system to access your account. +To maintain the security of your account when you perform a protected high-impact action on {% data variables.location.product_location %}, you must authenticate even though you're already signed in. {% data variables.product.company_short %} requires authentication for actions that can affect access to accounts and resources, including but not limited to: -* Modification of an associated email address -* Authorization of a third-party application -* Addition of a new SSH key -* Creation of a PAT or application +* **Account**: Deleting your user account, modifying an associated email address, adding a new SSH key, or authorizing third-party applications +* **Developer settings**: Generating or removing a client secret, creating {% data variables.product.pat_generic_plural %}, revoking all tokens, or transferring a {% data variables.product.prodname_oauth_app %} +* **Webhooks**: Creating, viewing, editing, or deleting repository, organization, or enterprise webhooks; viewing or redelivering webhook deliveries +* **Organization membership**: Sending or editing organization invitations, adding members directly, adding team members, or changing team roles +* **Organization security**: Changing two-factor authentication enforcement or other organization security settings +* **Enterprise settings**: Creating organizations in an enterprise or changing app access settings for an identity provider (IdP) IP allow list +* **Rulesets**: Creating and modifying rulesets at organization and repository level. +* **Recovery codes**: Viewing, downloading, printing, or regenerating authentication or SSO recovery codes After you authenticate to perform a sensitive action, your session is temporarily in "sudo mode." In sudo mode, you can perform sensitive actions without authentication. {% data variables.product.github %} has a two-hour session timeout period before prompting you for authentication again. During this time, any sensitive action that you perform will reset the timer. @@ -37,6 +41,16 @@ After you authenticate to perform a sensitive action, your session is temporaril {% endif %} +{% ifversion proof-of-presence %} + +## Proof of Presence for enterprise actions + +Enterprises can extend sudo mode with Proof of Presence (PoP). For protected high-impact actions, PoP requires you to reauthenticate through your enterprise's identity provider before the action can proceed. Follow the identity provider's prompts, including any required multi-factor authentication, then return to {% data variables.product.github %} to complete the action. + +{% data reusables.enterprise-accounts.proof-of-presence-supported-idps %} For more information, see [AUTOTITLE](/admin/configuring-settings/hardening-security-for-your-enterprise/configuring-proof-of-presence). + +{% endif %} + ## Confirming access for sudo mode To confirm access for sudo mode, you can authenticate with your password. Optionally, you can use a different authentication method, like a passkey, {% ifversion fpt or ghec %}a security key, {% data variables.product.prodname_mobile %}, or a 2FA code{% elsif ghes %}a security key or a 2FA code{% endif %}. 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 index 675c340e2dab..253765c2e9f2 100644 --- a/content/code-security/concepts/code-scanning/ai-powered-security-detections.md +++ b/content/code-security/concepts/code-scanning/ai-powered-security-detections.md @@ -19,7 +19,7 @@ While {% data variables.product.prodname_codeql %} provides high-precision stati During the {% data variables.release-phases.public_preview %}, AI Scan requires 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/organizations-and-enterprises/usage-based-billing). +Usage consumes {% data variables.product.prodname_ai_credits_short %}. See [AUTOTITLE](/copilot/concepts/billing-and-usage/organizations-and-enterprises/billing). ## How AI Scan works diff --git a/content/code-security/how-tos/maintain-quality-code/view-and-manage-cost.md b/content/code-security/how-tos/maintain-quality-code/view-and-manage-cost.md index 985bd3f2a042..1485db7b900c 100644 --- a/content/code-security/how-tos/maintain-quality-code/view-and-manage-cost.md +++ b/content/code-security/how-tos/maintain-quality-code/view-and-manage-cost.md @@ -37,7 +37,7 @@ It's important to understand how {% data variables.product.prodname_code_quality {% data variables.product.prodname_code_quality_short %} usage appears in the **same billing and usage views as your other products**, not in a separate {% data variables.product.prodname_code_quality_short %} meter. Where you look depends on how granular a breakdown you need: * **For a repository- or organization-level breakdown, download the billing usage report** from the "Billing and licensing" tab. This is the only place you can attribute {% data variables.product.prodname_code_quality_short %} spend, including {% data variables.product.prodname_actions %} minutes, down to a specific repository or organization. There's no equivalent view in the UI. See [AUTOTITLE](/billing/how-tos/products/view-productlicense-use). -* **For {% data variables.product.prodname_code_quality_short %}'s {% data variables.product.prodname_ai_credits_short %} usage over time, use the AI usage page** and group it by **Product** using the dropdown at the top right. This separates {% data variables.product.prodname_code_quality_short %} from your other AI products, like {% data variables.product.prodname_copilot_short %}, so you can track its share of the pool. To monitor the pool as a whole instead, see [AUTOTITLE](/copilot/concepts/billing/organizations-and-enterprises/usage-based-billing). +* **For {% data variables.product.prodname_code_quality_short %}'s {% data variables.product.prodname_ai_credits_short %} usage over time, use the AI usage page** and group it by **Product** using the dropdown at the top right. This separates {% data variables.product.prodname_code_quality_short %} from your other AI products, like {% data variables.product.prodname_copilot_short %}, so you can track its share of the pool. To monitor the pool as a whole instead, see [AUTOTITLE](/copilot/concepts/billing-and-usage/organizations-and-enterprises/billing). ## Monitoring your spend diff --git a/content/code-security/responsible-use/security-and-quality-ai-features.md b/content/code-security/responsible-use/security-and-quality-ai-features.md index 523a21bed646..7f57ffa8efbd 100644 --- a/content/code-security/responsible-use/security-and-quality-ai-features.md +++ b/content/code-security/responsible-use/security-and-quality-ai-features.md @@ -3,8 +3,7 @@ title: 'Application card: GitHub security and quality AI features' shortTitle: Security and quality AI features intro: Use GitHub's AI-powered code security and code quality features responsibly by understanding their purposes, capabilities, and limitations. versions: - fpt: '*' - ghec: '*' + feature: secret-scanning-ai-generic-secret-detection redirect_from: - /code-security/code-scanning/managing-code-scanning-alerts/about-autofix-for-codeql-code-scanning - /code-security/code-scanning/managing-code-scanning-alerts/responsible-use-autofix-code-scanning @@ -33,24 +32,36 @@ category: {% data reusables.rai.copilot.application-card-intro %} +{% ifversion ghes %} +For {% data variables.product.prodname_ghe_server %}, this application card applies only to generic secret detection for {% data variables.product.prodname_secret_scanning %}. +{% endif %} + ## 1. Overview -GitHub's security and quality platform includes several AI-powered capabilities that help developers find and fix security vulnerabilities, detect leaked secrets, and improve code quality. This application card covers the following experiences: +{% ifversion fpt or ghec %}GitHub's security and quality platform includes several AI-powered capabilities that help developers find and fix security vulnerabilities, detect leaked secrets, and improve code quality. {% endif %}This application card covers the following experiences: +{% ifversion fpt or ghec %} * **Copilot Autofix for code scanning**: Automatically generates fix suggestions for CodeQL alerts on pull requests and the default branch. +{% endif %} * **Generic secret detection**: Uses a model to identify unstructured secrets in source code that deterministic pattern matching cannot find. +{% ifversion fpt or ghec %} * **Custom pattern regex generator**: Uses AI to generate regular expressions for custom secret scanning patterns from natural language descriptions. * **GitHub Code Quality**: Surfaces code quality issues and offers LLM-powered fix suggestions on pull requests and the default branch. Also provides AI-powered automatic generation of code coverage workflows. +{% endif %} +{% ifversion fpt or ghec %} Copilot Autofix is an expansion of code scanning that provides users with targeted recommendations to help them fix code scanning alerts, avoiding the introduction of new security vulnerabilities. Potential fixes are generated automatically by large language models (LLMs) using data from the codebase and from code scanning analysis. Copilot Autofix is available for CodeQL analysis and does not require a GitHub Copilot subscription. Code scanning users can already see security alerts on their pull requests. However, developers often have little training in secure coding, so fixing these alerts requires substantial effort. Copilot Autofix lowers the barrier of entry by combining information on best practices with details of the codebase and alert to suggest a potential fix. Instead of starting with a search for information about the vulnerability, the developer starts with a code suggestion that demonstrates a potential solution for their codebase. The developer evaluates the potential fix to determine whether it is the best solution for their codebase and to ensure that it maintains the intended behavior. +{% endif %} Secret scanning's generic secret detection is an AI-powered expansion of secret scanning that identifies unstructured secrets in source code or other GitHub surfaces and generates an alert. GitHub Secret Protection and GitHub Advanced Security users can already receive secret scanning alerts for partner or custom patterns found in their source code, but unstructured secrets are not easily discoverable. Secret scanning uses models to identify these secrets. When a finding is detected, an alert is displayed in the "Generic" list of secret scanning alerts (under the **{% octicon "shield" aria-hidden="true" aria-label="shield" %} {% ifversion security-and-quality-tab %}Security and quality{% else %}Security{% endif %}** tab of the repository, organization, or enterprise), so that maintainers and security managers can review the alert and, where necessary, remove the credential or implement a fix. Generic secret detection does not require a GitHub Copilot subscription. +{% ifversion fpt or ghec %} Secret scanning's custom pattern regular expression generator makes it possible to define custom secret scanning patterns without knowledge of regular expressions. Users input a natural language description of what they want to detect, along with optional example strings, and the generator produces up to three candidate regular expressions. These patterns can then be validated via the dry-run mechanism before being deployed as custom patterns. The regular expression generator does not require a GitHub Copilot subscription. GitHub Code Quality helps users improve code reliability, maintainability, and overall project health by surfacing actionable feedback and offering automatic fixes for findings in pull requests and on the default branch. When Code Quality is enabled, two types of analysis run: CodeQL quality queries identify problems with the maintainability, reliability, or style of code, and LLM-powered analysis provides additional insights beyond what deterministic engines can find. When a quality issue is detected, Copilot Autofix suggests a relevant fix. On pull requests, results are displayed as comments left by the `github-code-quality` bot. On the default branch, LLM-powered findings are displayed in the **AI findings** dashboard under the **{% octicon "shield" aria-hidden="true" aria-label="shield" %} {% ifversion security-and-quality-tab %}Security and quality{% else %}Security{% endif %}** tab. Additionally, Code Quality can automatically generate a code coverage CI workflow for your repository using an AI-powered agent, reducing the manual effort required to set up coverage tracking. +{% endif %} The primary supported language for GitHub Code Security AI features is English. @@ -58,51 +69,66 @@ The primary supported language for GitHub Code Security AI features is English. The following list provides a glossary of key terms related to GitHub Code Security AI features: +{% ifversion fpt or ghec %} * **CodeQL**: GitHub's semantic code analysis engine for identifying security vulnerabilities in source code. * **Copilot Autofix**: GitHub's LLM-powered feature that automatically generates fix suggestions for code scanning alerts. Copilot Autofix is available for CodeQL analysis and does not require a GitHub Copilot subscription. * **Large language model (LLM)**: A type of neural network trained on a large body of text data that can generate, analyze, and transform natural language and code. Copilot Autofix uses one or more LLMs to process code scanning alerts and produce fix suggestions. +{% endif %} * **AI detection for secret scanning**: AI-powered capabilities that extend secret scanning, including generic secret detection. Does not require a GitHub Copilot subscription. * **Generic secret detection**: AI identification of unstructured secrets (such as passwords) that are not covered by partner or custom patterns. Generic secret detection uses models to scan for password-like strings in source code. +{% ifversion fpt or ghec %} * **Custom pattern**: A user-defined regular expression used by secret scanning to detect secrets that match a specific format. The custom pattern regular expression generator helps create these patterns from natural language descriptions. * **SARIF**: Static Analysis Results Interchange Format—the standard format CodeQL uses to report code scanning findings, including alert locations and descriptions. * **GitHub Code Quality**: A feature that surfaces code quality issues and offers LLM-powered fixes. Code Quality combines CodeQL quality queries with LLM-powered analysis to identify maintainability, reliability, and style issues. * **AI findings**: The dashboard under the **{% octicon "shield" aria-hidden="true" aria-label="shield" %} {% ifversion security-and-quality-tab %}Security and quality{% else %}Security{% endif %}** tab where LLM-powered Code Quality findings for the default branch are displayed. +{% endif %} ## 3. Key features or capabilities The key features and capabilities outlined here describe what GitHub Code Security AI features are designed to do and how they perform across supported tasks. +{% ifversion fpt or ghec %} * **Automated fix suggestions for security alerts**: Copilot Autofix automatically generates code change suggestions for CodeQL alerts found on pull requests and on the default branch. Each suggestion includes both the proposed code change and a natural language explanation of the fix. * **Alert-to-fix translation**: Copilot Autofix translates the description and location of a code scanning alert into actionable code changes that may resolve the underlying security vulnerability. The system uses CodeQL alert data in SARIF format, surrounding code snippets, and query help text to generate relevant fixes. * **Multi-language support**: Copilot Autofix supports fix generation for a subset of queries included in the default and security-extended CodeQL query suites for C#, C/C++, Go, Java/Kotlin, Swift, JavaScript/TypeScript, Python, Ruby, and Rust. For more information on these query suites, see [AUTOTITLE](/code-security/concepts/code-scanning/codeql/codeql-query-suites#built-in-codeql-query-suites). +{% endif %} * **AI-powered password detection**: Secret scanning's generic secret detection scans repository content using AI to identify unstructured secrets (like passwords) that deterministic pattern matching cannot find. Detected secrets are surfaced as alerts in the secret scanning alert list under the **{% octicon "shield" aria-hidden="true" aria-label="shield" %} {% ifversion security-and-quality-tab %}Security and quality{% else %}Security{% endif %}** tab. +{% ifversion fpt or ghec %} * **AI-powered regular expression generation**: Secret scanning's regular expression generator takes a natural language description of the pattern you want to detect, along with optional example strings, and produces up to three candidate regular expressions. Each result includes an AI-generated plain language description, and you can validate patterns via a dry run before deployment. * **Code quality issue detection**: GitHub Code Quality runs CodeQL quality queries on changed code in pull requests and periodically on the full default branch. These queries identify maintainability, reliability, and style issues. * **LLM-powered code quality analysis**: After each push to the default branch, an LLM analyzes recently changed files for quality issues beyond what deterministic engines can find. Findings are displayed in the **AI findings** dashboard. * **Automated fix suggestions for quality findings**: When a quality issue is detected by either type of analysis, Copilot Autofix generates a fix suggestion. On pull requests, the `github-code-quality` bot posts a comment with the suggested change. +{% endif %} ## 4. Intended uses GitHub Code Security AI features can be used in multiple scenarios across a variety of industries. Some examples of use cases include: +{% ifversion fpt or ghec %} * **Accelerating remediation of security vulnerabilities**: Use Copilot Autofix to quickly generate fix suggestions for CodeQL alerts, reducing the time and expertise required to address security issues found during code scanning. * **Reducing the barrier to secure coding**: Copilot Autofix helps developers with limited secure-coding training. Instead of researching vulnerabilities independently, developers start with a code suggestion that demonstrates a potential solution for their codebase. * **Streamlining pull request review**: When code scanning finds alerts on a pull request, Copilot Autofix provides suggested fixes inline, helping developers resolve security issues before merging. * **Fixing alerts on the default branch**: Copilot Autofix can also generate fix suggestions for existing alerts on the default branch, helping teams reduce their backlog of security findings. +{% endif %} * **Detecting leaked passwords in source code**: Use generic secret detection to find unstructured secrets in repositories that fall outside the coverage of partner and custom secret scanning patterns. * **Triaging credentials with contextual alerts**: When a password is detected, an alert with AI-detection context is displayed in the alerts list, enabling maintainers and security managers to review the finding and take action. +{% ifversion fpt or ghec %} * **Creating custom secret scanning patterns without regex expertise**: Use the regular expression generator to define custom patterns by describing what you want to detect in natural language, removing the need to write regular expressions manually. * **Validating generated patterns before deployment**: After generating regular expressions, use the dry-run mechanism to test patterns across your repository or organization before deploying them as custom patterns. * **Surfacing code quality issues across a repository**: Use GitHub Code Quality to identify maintainability, reliability, and style issues so developers and administrators can quickly prioritize areas of risk. * **Accelerating remediation of code quality findings**: Copilot Autofix suggests fixes for quality findings, combining information on best practices with details of the codebase to propose a potential fix directly on the pull request or in the AI findings dashboard. * **Providing actionable feedback on pull requests**: The `github-code-quality` bot posts comments with suggested fixes on pull requests, helping developers address quality issues before merging. +{% endif %} ## 5. Models and training data +{% ifversion fpt or ghec %} Copilot Autofix uses internal GitHub Copilot APIs interfacing with the large language models, which produce both suggested fixes in code and explanatory text for those fixes. +{% endif %} Generic secret detection uses models to scan for unstructured secrets. +{% ifversion fpt or ghec %} The custom pattern regular expression generator uses LLMs and the GitHub Copilot API to generate regular expressions that match user-provided descriptions and examples. GitHub Code Quality's LLM-powered analysis uses Copilot language models to analyze recently changed files for quality issues. The CodeQL quality queries component does not use an LLM. Copilot Autofix for Code Quality findings uses the same LLM pipeline as Copilot Autofix for code scanning. @@ -110,9 +136,11 @@ GitHub Code Quality's LLM-powered analysis uses Copilot language models to analy For a comparison of the models available for Copilot, see [AUTOTITLE](/copilot/reference/ai-models/model-comparison). For the full list of supported models, see [AUTOTITLE](/copilot/reference/ai-models/supported-models). For information on where models are hosted, see [AUTOTITLE](/copilot/reference/ai-models/model-hosting). To learn more about the data used to train the foundation models behind GitHub security and quality, see [What data has GitHub Copilot been trained on?](https://github.com/features/copilot#faq) in the GitHub Copilot FAQ. Data handled by Copilot Autofix is not employed for LLM training purposes. The use of this feature is governed by the existing terms and conditions associated with GitHub Advanced Security. For more information, see [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#advanced-security){% ifversion fpt %}.{% else %} in the Free, Pro, & Team documentation.{% endif %} +{% endif %} ## 6. Performance +{% ifversion fpt or ghec %} When Copilot Autofix is enabled for a repository, code scanning alerts are processed through the following pipeline: 1. **Input processing**: When a code scanning alert is identified, GitHub assembles the relevant data into a prompt for the language model. This data includes: @@ -125,6 +153,7 @@ When Copilot Autofix is enabled for a repository, code scanning alerts are proce 1. **Output formatting**: The suggestion is stored within the code scanning backend and displayed as an inline suggestion on the pull request or alert detail page. No user interaction is needed beyond enabling code scanning on the codebase and creating a pull request. ### Differences by experience +{% endif %} **AI secret detection** processes input and produces output as follows: @@ -133,6 +162,7 @@ When Copilot Autofix is enabled for a repository, code scanning alerts are proce 1. **Response generation**: The model verifies that the identified strings included in the response actually exist in the input. 1. **Output formatting**: Detected strings are surfaced as alerts on the secret scanning alerts page in a separate list from regular secret scanning alerts. Each alert notes that it was detected by AI.{% ifversion secret-scanning-ai-generic-secret-detection %} For information on how to view alerts for generic secrets, see [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-secret-scanning-alerts/viewing-alerts).{% endif %} +{% ifversion fpt or ghec %} **Custom pattern regex generator** processes input and produces output as follows: 1. **Input processing**: Users input a natural language text description of the pattern they want to detect, along with optional example strings that should be matched. @@ -153,11 +183,13 @@ When Copilot Autofix is enabled for a repository, code scanning alerts are proce 1. **Language model analysis**: The LLM analyzes the finding and generates a potential fix. 1. **Response generation**: If the LLM can generate a fix, it produces a suggested code change. 1. **Output formatting**: The `github-code-quality` bot posts a comment on the pull request with the suggested change. Users can also request autofix generation for results on the default branch. +{% endif %} ## 7. Limitations Understanding GitHub Code Security AI features' limitations is crucial to determine if it is used within safe and effective boundaries. While we encourage customers to leverage GitHub Code Security AI features in their innovative solutions or applications, it's important to note that GitHub Code Security AI features was not designed for every possible scenario. We encourage users to refer to [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms) as well as the following considerations when choosing a use case: +{% ifversion fpt or ghec %} * **Non-determinism**: Copilot Autofix uses a generative model that is non-deterministic. Even with the same alert and code, it might fail to produce a viable suggestion, or the suggestion might vary across attempts. * **Problem complexity and context**: Some security alerts—such as those that require tracing data flow across a complex, multi-file codebase, or those that represent subtle logic flaws—could be difficult for the model to resolve. * **File size**: If the affected code is within a very large file or repository, the context provided to the LLM may be truncated. When the context is limited, the feature will not attempt a fix. @@ -170,6 +202,7 @@ Understanding GitHub Code Security AI features' limitations is crucial to determ * **Security vulnerabilities and misleading fixes**: The system may suggest fixes that fail to remediate the underlying vulnerability or introduce new vulnerabilities. * **Partial fixes**: The system may suggest fixes that only partially address the security vulnerability or only partially preserve intended code functionality. * **Dependency changes**: Suggested fixes may include adding or updating software dependencies. The system does not know which dependency versions are supported or secure, and may suggest fabricated dependencies published under statistically probable names. Always verify dependency changes before merging. +{% endif %} ### Limitations specific to AI secret detection @@ -178,6 +211,7 @@ Understanding GitHub Code Security AI features' limitations is crucial to determ * The file path contains "test", "mock", or "spec" * The file extension is `.cs`, `.go`, `.java`, `.js`, `.kt`, `.php`, `.py`, `.rb`, `.scala`, `.swift`, or `.ts`. +{% ifversion fpt or ghec %} ### Limitations specific to the custom pattern regex generator * **Incomplete pattern coverage**: Generated regular expressions may not match all intended tokens. The quality of results depends on the specificity and clarity of the input description. @@ -191,11 +225,13 @@ Understanding GitHub Code Security AI features' limitations is crucial to determ * **Shared limitations with Copilot code review**: Code Quality's LLM-powered analysis uses the same underlying language model and analysis engine as Copilot code review. It shares similar limitations, including incomplete detection, false positives, code suggestion accuracy, and potential biases. For more information, see [AUTOTITLE](/copilot/responsible-use/agents). * **Best-effort autofix**: Copilot Autofix for Code Quality findings operates on a best-effort basis and is not guaranteed to generate a fix for every finding. * **Review required**: You must always review suggestions from Copilot Autofix and edit changes as needed before accepting them. +{% endif %} ## 8. Evaluations {% data reusables.rai.copilot.application-card-evaluations %} +{% ifversion fpt or ghec %} ### Performance and quality evaluations GitHub Security AI features are evaluated across its supported surfaces using a combination of industry-standard benchmarks (e.g., SWE-Bench) and internally developed evaluation suites. Benchmark tasks are sourced from public open-source repositories and synthetic scenarios; no real user queries or customer code are used without permission. Each evaluation includes multiple independent runs to account for nondeterminism in model outputs. Key metrics include resolution rate (percentage of tasks successfully completed), token efficiency, latency, and tool call reliability. Models are re-evaluated when updates are made and monitored continuously in production via error rates, response latency, and aggregate usage patterns. @@ -203,6 +239,7 @@ GitHub Security AI features are evaluated across its supported surfaces using a ### Performance and quality evaluation methods New models undergo a staged evaluation process before deployment to Code Security, Code Quality, and Secret Protection. Integrator teams run benchmark suites specific to their surface, testing the model on representative coding tasks such as bug fixes, code generation, and multi-file refactoring. Results are reviewed against established baselines and existing production models. Models must meet or exceed baseline performance across key metrics like resolution rate, token efficiency, and latency, before advancing to the next stage. +{% endif %} ### Risk and safety evaluations @@ -214,6 +251,7 @@ New models undergo a staged evaluation process before deployment to Code Securit ### Custom evaluations +{% ifversion fpt or ghec %} GitHub uses an automated test harness to continuously monitor the quality of Copilot Autofix suggestions. The test harness includes a set of over 2,300 alerts from a diverse set of public repositories where the highlighted code has test coverage. Suggestions for these alerts are tested to determine how much a developer would need to edit them before committing them to the codebase. For many of the test alerts, suggestions generated by the LLM could be committed as-is to fix the alert while continuing to successfully pass all existing CI tests. GitHub tests the effectiveness of suggestions by merging all suggested changes, unedited, before running code scanning and the repository's unit tests on the resulting code: @@ -226,24 +264,31 @@ GitHub tests the effectiveness of suggestions by merging all suggested changes, In addition, GitHub spot-checks many successful suggestions and verifies that they fix the alert without introducing new problems. When one or more of these checks fail, manual triage showed that in many cases the proposed fix was nearly correct but needed some minor modifications that a user could identify and manually perform. The system is also stress-tested to check for potential harm (red teaming), and a filtering system on the LLM helps prevent potentially harmful suggestions from being displayed to users. +{% endif %} AI secret detection has been subject to Responsible AI Red Teaming and GitHub continues to monitor the efficacy and safety of the feature over time. +{% ifversion fpt or ghec %} Custom pattern regex generator results are validated through the dry-run mechanism, which allows users to test generated patterns across their repository or organization before deploying them as custom patterns. This built-in validation step helps ensure that generated regular expressions perform as expected before they are used in production. GitHub Code Quality's LLM-powered analysis shares the evaluation framework of Copilot code review. Copilot Autofix suggestions for Code Quality findings follow the same test harness as Copilot Autofix for code scanning. +{% endif %} ## 9. Safety components and mitigations +{% ifversion fpt or ghec %} * **Human-in-the-loop review**: Copilot Autofix presents all suggestions as proposed code changes that require explicit developer review and acceptance before being applied. Developers must evaluate each suggestion and verify it maintains the codebase's intended behavior. * **Content filtering**: A filtering system on the LLM detects and prevents potentially harmful suggestions from being displayed to users. The system is stress-tested through red teaming to identify potential vulnerabilities. * **Internal quality testing**: Suggestions that fail internal testing are not displayed to users. Fix generation is only shown when the system has sufficient confidence in the suggestion's quality. * **Opt-in/opt-out controls**: Copilot Autofix is allowed by default and enabled for every repository using CodeQL, but administrators can disable Copilot Autofix at the enterprise, organization, and repository levels. For more information, see [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning). * **No training on customer data**: Data handled by Copilot Autofix is not employed for LLM training purposes. The use of this feature is governed by the existing terms and conditions associated with GitHub Advanced Security. +{% endif %} * **False positive feedback loop**: When users close a generic secret detection alert and mark the reason as "False positive," GitHub uses the false positive volume to improve the model. GitHub does not have access to the secret literals themselves. +{% ifversion fpt or ghec %} * **Dry-run validation for generated patterns**: Generated regular expressions from the custom pattern regex generator must go through a dry-run validation step before deployment. Users explicitly import a result into the custom pattern form and test it across their repository or organization, ensuring patterns perform as expected before they are used in production. * **Explicit user action required**: The regex generator does not automatically deploy patterns. Users must click **Use result** to copy a generated expression into the custom pattern form, then manually save and enable the pattern. * **Feedback mechanism for Code Quality**: Users can provide feedback on Code Quality suggestions using the thumbs up and thumbs down buttons on the `github-code-quality` bot's comments, helping GitHub improve suggestion quality. +{% endif %} ## 10. Best practices for deploying and adopting GitHub Code Security AI features @@ -251,42 +296,54 @@ Responsible AI is a shared commitment between GitHub and its customers. While Gi * **Exercise caution and evaluate outcomes when using GitHub Security AI features for consequential decisions or in sensitive domains**: {% data reusables.rai.copilot.application-card-consequential-decisions %} * **Evaluate legal and regulatory considerations**: {% data reusables.rai.copilot.application-card-evaluate-legal-regulatory %} +{% ifversion fpt or ghec %} * **Always review suggestions before accepting**: Evaluate the proposed code change to ensure it correctly fixes the security vulnerability without changing the intended behavior of your code. Having good test coverage helps verify that a fix does not change the behavior of the codebase. * **Verify CI tests pass**: After committing a suggested fix or modified fix, always verify that continuous integration testing (CI) for the codebase continues to pass and that the alert is shown as resolved before merging your pull request. * **Review dependency changes carefully**: If a suggested fix includes changes to dependencies, verify that any added or updated dependencies are secure, supported, and maintain the intended behavior of the codebase. Use dependency management solutions, such as the dependency review API and action, to evaluate changes. For more information, see [AUTOTITLE](/code-security/concepts/supply-chain-security/dependency-review). +{% endif %} * **Close false positive alerts appropriately**: Since AI secret detection may generate more false positives than partner pattern detection, review the accuracy of each alert. When you verify an alert to be a false positive, close the alert and mark the reason as "False positive" in the GitHub UI. This feedback helps improve the model. +{% ifversion fpt or ghec %} * **Validate generated regex patterns with a dry run**: When using the custom pattern regex generator, always perform a dry run across representative repositories before deploying a generated pattern organization-wide. * **Be specific with descriptions**: To improve the quality of generated regular expressions, be as specific as possible with your natural language descriptions and include diverse example strings that represent the patterns you want to detect. * **Review all generated patterns**: Carefully review each of the generated regular expressions, including the AI-generated plain language descriptions, and consider modifying results to more fully meet your needs. You remain ultimately responsible for any custom patterns you decide to use. * **Review Code Quality findings before applying fixes**: Always verify the accuracy and applicability of Code Quality findings and Autofix suggestions to your codebase before accepting them. * **Provide feedback on Code Quality suggestions**: Use the thumbs up and thumbs down buttons on the `github-code-quality` bot's comments to help improve the tool and address any concerns or limitations. +{% endif %} * **Exercise human oversight when appropriate**: Human oversight is an important safeguard when interacting with AI applications. While we continuously improve our AI applications, AI might still make mistakes. The outputs generated may be inaccurate, incomplete, biased, misaligned, or irrelevant to your intended goals. This could happen due to various reasons, such as ambiguity in the inputs or limitations of the underlying models. As such, users should review the responses generated by GitHub Code Security AI features and verify that they match their expectations and requirements. * **Be aware of the risk of overreliance**: {% data reusables.rai.copilot.application-card-overreliance %} * **Exercise caution when designing agentic AI in sensitive domains**: {% data reusables.rai.copilot.application-card-agentic-ai-caution %} +{% ifversion fpt or ghec %} * **Enable CI testing on pull requests**: Ensure continuous integration testing is in place before enabling Copilot Autofix, so that functional requirements are verified after developers apply fixes. * **Use dependency management solutions**: Enable dependency review on pull requests to catch potentially risky dependency changes introduced by Autofix suggestions. * **Review security overview metrics**: Use your organization's security overview dashboard to view the total number of Copilot Autofix suggestions generated on open and closed pull requests for a given time period. For more information, see [AUTOTITLE](/code-security/reference/security-at-scale/overview-dashboard-metrics#pull-request-alerts-fixed-with-copilot-autofix-suggestions). +{% endif %} * **Evaluate false-positive volume for secret detection**: Evaluate the false-positive volume and establish triage processes for the alerts list. +{% ifversion fpt or ghec %} * **Monitor Code Quality suggestion volume and quality**: Evaluate the volume and quality of Code Quality suggestions and adjust enablement as appropriate for your organization. +{% endif %} ## 11. Learn more about GitHub Security AI features For additional guidance on the responsible use of GitHub Security AI features, we recommend reviewing the following documentation: +{% ifversion fpt or ghec %} * [AUTOTITLE](/code-security/concepts/code-scanning/code-scanning-alerts) * [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/triage-alerts-in-pull-requests#working-with-copilot-autofix-suggestions-for-alerts-on-a-pull-request) * [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/resolve-alerts#generating-a-suggested-fix) * [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-code-scanning-alerts/disabling-autofix-for-code-scanning) +{% endif %} * [AUTOTITLE](/free-pro-team@latest/site-policy/github-terms/github-terms-for-additional-products-and-features#advanced-security) * [AUTOTITLE](/code-security/concepts/secret-security/secret-scanning) * [AUTOTITLE](/code-security/how-tos/secure-your-secrets/detect-secret-leaks/enabling-secret-scanning-for-ai-detected-secrets) -* [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-secret-scanning-alerts){% ifversion ghec %} -* [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-generic-secret-detection-for-secret-scanning-in-your-enterprises-repositories){% endif %} +* [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-secret-scanning-alerts){% ifversion ghec or ghes %} +* [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-detection-for-secret-scanning-in-your-enterprises-repositories){% endif %} +{% ifversion fpt or ghec %} * [AUTOTITLE](/code-security/how-tos/secure-your-secrets/customize-leak-detection/generating-regular-expressions-for-custom-patterns-with-ai) * [AUTOTITLE](/code-security/how-tos/secure-your-secrets/customize-leak-detection/define-custom-patterns) * [AUTOTITLE](/code-security/concepts/code-quality/code-quality) * [AUTOTITLE](/copilot/responsible-use/agents) * [Community discussion for Code Quality feedback](https://github.com/orgs/community/discussions/177488) +{% endif %} ### Learn more about responsible AI diff --git a/content/copilot/concepts/agents/code-review.md b/content/copilot/concepts/agents/code-review.md index 564aff871051..259d3dbf187a 100644 --- a/content/copilot/concepts/agents/code-review.md +++ b/content/copilot/concepts/agents/code-review.md @@ -132,10 +132,12 @@ When {% data variables.copilot.copilot_code-review_short %} is enabled for these By default, {% data variables.product.prodname_copilot_short %} only reviews a pull request if you assign it to the pull request. However, you can configure automatic reviews. -* **Individual users** on the {% data variables.copilot.copilot_pro_short %} or {% data variables.copilot.copilot_pro_plus_short %} plan can configure {% data variables.product.prodname_copilot_short %} to automatically review all pull requests they create. +* **Users** can configure {% data variables.product.prodname_copilot_short %} to automatically review the pull requests they create. This is available on the {% data variables.copilot.copilot_pro_short %}, {% data variables.copilot.copilot_pro_plus_short %}, and {% data variables.copilot.copilot_max_short %} plans, and with a {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %} license. It is not available for {% data variables.enterprise.prodname_managed_users %}. * **Repository owners** can configure {% data variables.product.prodname_copilot_short %} to automatically review all pull requests in the repository that are created by people with access to {% data variables.product.prodname_copilot_short %}. * **Organization owners** can configure {% data variables.product.prodname_copilot_short %} to automatically review all pull requests in some or all of the repositories in the organization where the pull request is created by a {% data variables.product.prodname_copilot_short %} user. +{% data variables.product.prodname_copilot_short %} evaluates pull requests against two separate configurations: a user's settings and any applicable ruleset. These configurations are not hierarchical; neither inherits from or overrides the other. A pull request is reviewed automatically when at least one configuration is enabled. If both configurations are enabled on a pull request, {% data variables.product.prodname_copilot_short %} still posts only one review. + If your organization has enabled {% data variables.copilot.copilot_code-review_short %} without a {% data variables.product.prodname_copilot_short %} license, automatic reviews also apply to pull requests created by organization members without a license. This applies to repositories covered by a policy where automatic reviews are enabled. For more information, see [{% data variables.copilot.copilot_code-review_short %} without a {% data variables.product.prodname_copilot_short %} license](#copilot-code-review-without-a-copilot-license). @@ -151,6 +153,8 @@ The triggers for automatic code review depend on the configuration settings. * Review draft pull requests: * Pull requests are automatically reviewed while they are still drafts, before you switch them to "Open". +When a pull request qualifies for automatic review, **Review new pushes** and **Review draft pull requests** apply if either the author's settings or an applicable ruleset turns them on. You cannot use your own settings to turn off push or draft reviews that a ruleset has turned on. + For full instructions, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/set-up-copilot/configure-code-review). > [!NOTE] @@ -158,17 +162,28 @@ For full instructions, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/set-up ## Review effort level -{% data variables.copilot.copilot_code-review_short %} supports multiple review effort levels, so you can choose the level of thoroughness that matches the criticality of your code. +{% data variables.copilot.copilot_code-review_short %} supports multiple {% data variables.product.prodname_copilot_short %} review effort levels, so you can choose the level of thoroughness that matches the criticality of your code. * **Lite**: Standard review. Provides fast, targeted feedback on common issues such as bugs, security vulnerabilities, and style inconsistencies (default). * **Balanced**: Routes pull requests to a higher-reasoning model for longer analysis of complex logic, security-sensitive code, and cross-service changes. Balanced reviews use more {% data variables.product.prodname_ai_credits_short %}, and may consume marginally more {% data variables.product.prodname_actions %} minutes, than Lite reviews. Use Balanced for security-sensitive code, multi-service pull requests, or repositories with strict quality standards. Use Lite for routine changes where fast feedback is more important than exhaustive analysis. -You can select the review effort level when requesting a review in the pull request, under the **Reviewers** section where {% data variables.product.prodname_copilot_short %} appears as a reviewer. Organization owners can set a default review effort level for automatic code reviews in their organization. Repository administrators can override the organization default for a specific repository. +You can select {% data variables.product.prodname_copilot_short %} review effort when requesting a review in the pull request, under the **Reviewers** section where {% data variables.product.prodname_copilot_short %} appears as a reviewer. You can also set a default {% data variables.product.prodname_copilot_short %} review effort in your {% data variables.copilot.copilot_code-review_short %} settings. Organization owners can set a default {% data variables.product.prodname_copilot_short %} review effort for automatic code reviews in their organization. Repository administrators can override the organization default for a specific repository. + +When {% data variables.product.prodname_copilot_short %} determines which review effort to use, it checks the following options in order and uses the first one that applies: + +1. A {% data variables.product.prodname_copilot_short %} review effort chosen when the review is requested +1. A {% data variables.product.prodname_copilot_short %} review effort previously used on this pull request +1. The requestor's {% data variables.product.prodname_copilot_short %} review effort. For a new pull request, the requestor is the author. When someone marks a draft ready for review, that person is the requestor. +1. A {% data variables.product.prodname_copilot_short %} review effort set for the repository +1. A {% data variables.product.prodname_copilot_short %} review effort set for the organization, or the repository owner's {% data variables.product.prodname_copilot_short %} review effort on a user-owned repository +1. {% data variables.product.github %}'s built-in default, which is Lite. Some owners have Balanced as the built-in default. After {% data variables.copilot.copilot_code-review_short %} reviews a pull request, the pull request overview comment shows the effort level used for each review run. +For configuration steps, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/set-up-copilot/configure-code-review). + ## {% data variables.product.prodname_copilot_short %} approvals > [!NOTE] diff --git a/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md b/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md index c38d4c0bca9e..60b59392e8a3 100644 --- a/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md +++ b/content/copilot/concepts/agents/copilot-cli/cancel-and-roll-back.md @@ -16,7 +16,7 @@ category: When you work in an interactive {% data variables.copilot.copilot_cli_short %} session, you can press Esc or Ctrl+C to control what {% data variables.product.prodname_copilot_short %} is doing. Both keypresses can cancel operations, but they work slightly differently: -* Ctrl+C acts immediately, without a confirming second press—removing any queued prompts first (one per press), then canceling the current operation. +* Ctrl+C acts immediately, without a confirming second press—clearing any queued prompts and canceling the current operation. * A single Esc keypress gives you more gradual, staged control. While {% data variables.product.prodname_copilot_short %} is actively working, a single Esc doesn't cancel right away—it shows a reminder, and a second press interrupts the current operation. In a local session, any queued prompts are then processed as the next turn. In a remote-backed or attached session, the second press fully cancels the operation instead, and queued prompts are not carried over to a follow-up turn. If {% data variables.product.prodname_copilot_short %} has already made changes and you want to undo them, you can roll back to a previous point in the session. As {% data variables.product.prodname_copilot_short %} works, {% data variables.copilot.copilot_cli_short %} tracks the file changes it makes as it responds to each prompt. This lets you rewind to an earlier point by pressing Esc twice when {% data variables.product.prodname_copilot_short %} is idle and the input area is empty. When you rewind, you choose whether to rewind the conversation only, or to also restore the files that {% data variables.product.prodname_copilot_short %} changed. @@ -48,7 +48,7 @@ The main difference between these two ways of canceling an operation is that Esc when you want a confirming keypress before interrupting an operation. If a permission dialog appears and you want to deny that specific request, pressing Esc once rejects the request and stops the current operation. If you've queued follow-up prompts in a local session, pressing Esc twice interrupts the current operation and processes the queued prompts as the next turn. In a remote-backed or attached session, pressing Esc twice fully cancels the operation instead, and queued prompts are not run as a follow-up turn. -Use Ctrl+C when you want to cancel without the confirming second press that Esc requires. If no prompts are queued, a single Ctrl+C immediately cancels the active operation. If you have queued prompts, each Ctrl+C removes the most recently queued prompt—one per press—and cancels the active operation only once the queue is empty. Any file write that is already in progress will complete—files are not left corrupted mid-write—but any remaining planned changes are abandoned. Pressing Ctrl+C a second time within two seconds, when the input area is empty, exits the session entirely. +Use Ctrl+C when you want to cancel without the confirming second press that Esc requires. A single Ctrl+C immediately cancels the active operation and clears any queued prompts. Any file write that is already in progress will complete—files are not left corrupted mid-write—but any remaining planned changes are abandoned. Pressing Ctrl+C a second time within two seconds, when the input area is empty, exits the session entirely. As a rule of thumb, use Esc when you want to intervene selectively, and Ctrl+C when you want to stop and start over. diff --git a/content/copilot/concepts/enterprise/default-availability.md b/content/copilot/concepts/enterprise/default-availability.md new file mode 100644 index 000000000000..80b3db77d3b9 --- /dev/null +++ b/content/copilot/concepts/enterprise/default-availability.md @@ -0,0 +1,73 @@ +--- +title: About default availability of {% data variables.product.prodname_copilot_short %} features and models +shortTitle: Default availability +intro: Policies control whether unconfigured features and models default to enabled or disabled. +product: '{% data variables.copilot.copilot_business_short %} and {% data variables.copilot.copilot_enterprise_short %}' +versions: + feature: copilot +contentType: concepts +category: + - Learn about Copilot + - Manage Copilot for a team +redirect_from: + - /copilot/concepts/models/automatic-enablement + - /copilot/concepts/models/default-availability + - /copilot/concepts/enterprise/default-model-availability +--- + +{% data reusables.copilot.default-availability-policies %} + + + +## Default availability of features + +The **Default policy for new features** policy is available to configure but is **not** currently active. It will start applying to new and existing GA features from October 22, 2026. In your policy settings, you will see a banner showing how many eligible policies are currently unconfigured, so you can assess the impact of your global default and explicitly configure individual policies before October 22. + +This policy is enabled by default. If you don't take action, unconfigured features will be enabled on October 22. + + + +### What does the policy do? + +Your setting for this policy determines the enablement status of: + +* New GA (general availability) features +* Features that move from preview to GA +* Existing GA features that are **Unconfigured** in your policy settings + +The policy can be configured in an enterprise and its organizations. At the enterprise level, it applies to features labeled as **Unconfigured**. At the organization level, it applies to features that an enterprise owner has set to **Let organizations decide**, but that an organization owner has not explicitly configured. + +The policy does **not** apply to features in preview. + +### What counts as a feature? + +For the purposes of this policy, a "feature" refers to any policy configured on an enterprise's "Features & clients" page (`github.com/enterprises/ENTERPRISE/ai-controls/copilot/features`), **plus**: + +* The **{% data variables.copilot.copilot_code-review_short %}** policy on the "Agents" page +* The **MCP servers in {% data variables.product.prodname_copilot_short %}** policy on the "MCP" page + +The following policies are exceptions and are **not** affected: + +* Restrictive model policies on {% data variables.enterprise.data_residency_site %}: **Restrict Copilot to data residency models** and **Restrict Copilot to FedRAMP models** +* **Store local sessions in the Cloud** for {% data variables.copilot.copilot_cli_short %} and {% data variables.product.prodname_vscode_shortname %} + +## Default availability of models + +The **Default availability for released models** policy is active and affects new and unconfigured GA models. + +### Which models follow the policy? + +{% data reusables.copilot.model-autoenablement-excluded-models %} + +## How do I prevent default enablement? + +To disable default enablement entirely, disable the default policies in your enterprise or organization's settings. You can set a policy for the entire enterprise, or disable the policy only in organizations with stricter compliance requirements. + +If you keep the default availability policies enabled, you can explicitly disable individual features and models so that they are not eligible for automatic enablement. + +* For features, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-enterprise-policies) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/manage-policies). +* For models, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-availability-of-default-models) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/manage-default-models). + +## How do I prepare for new releases? + +We recommend keeping up with new releases and GA announcements so you can choose your enablement settings. New features and models are announced on {% data variables.product.github %}'s changelog. For more information, see [AUTOTITLE](/copilot/concepts/enterprise/learning-about-new-features-and-models). diff --git a/content/copilot/concepts/enterprise/default-model-availability.md b/content/copilot/concepts/enterprise/default-model-availability.md deleted file mode 100644 index f8e8b32aa093..000000000000 --- a/content/copilot/concepts/enterprise/default-model-availability.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: About default availability of {% data variables.product.prodname_copilot_short %} models -shortTitle: Default model availability -intro: A policy controls whether unconfigured models default to enabled or disabled. -product: '{% data variables.copilot.copilot_business_short %} and {% data variables.copilot.copilot_enterprise_short %}' -versions: - feature: copilot -contentType: concepts -category: - - Learn about Copilot - - Manage Copilot for a team -redirect_from: - - /copilot/concepts/models/automatic-enablement - - /copilot/concepts/models/default-availability - - /copilot/concepts/enterprise/default-availability ---- - -For enterprises with {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %} plans, the **Default availability for released models** policy controls whether unconfigured generally available (GA) models default to enabled or disabled. If this policy is enabled, users benefit from the latest models without the need for administrator intervention. - -## Which models follow the policy? - -{% data reusables.copilot.model-autoenablement-excluded-models %} - -## How do I prevent default enablement? - -To disable default enablement entirely, disable the **Default availability for released models** policy in your enterprise or organization's models policies. You can set a policy for the entire enterprise, or disable the policy only in organizations with stricter compliance requirements. - -If you keep the **Default availability for released models** policy enabled, you can explicitly disable individual models so that they are not eligible for automatic enablement. - -For instructions on managing model policies, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-availability-of-default-models) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/manage-default-models). - -## How do I prepare for new models? - -We recommend keeping up with new model releases so you can choose your enablement settings for each one. New models are announced on {% data variables.product.github %}'s changelog. For more information, see [AUTOTITLE](/copilot/concepts/enterprise/learning-about-new-features-and-models#learning-about-new-copilot-models). diff --git a/content/copilot/concepts/enterprise/index.md b/content/copilot/concepts/enterprise/index.md index d5564c05253e..714556324bee 100644 --- a/content/copilot/concepts/enterprise/index.md +++ b/content/copilot/concepts/enterprise/index.md @@ -6,7 +6,7 @@ versions: feature: copilot children: - /policies - - /default-model-availability + - /default-availability - /fedramp-models - /learning-about-new-features-and-models - /agent-management diff --git a/content/copilot/concepts/enterprise/learning-about-new-features-and-models.md b/content/copilot/concepts/enterprise/learning-about-new-features-and-models.md index 74245e782348..2ecec9d8ac51 100644 --- a/content/copilot/concepts/enterprise/learning-about-new-features-and-models.md +++ b/content/copilot/concepts/enterprise/learning-about-new-features-and-models.md @@ -60,10 +60,6 @@ You can find information about the models available and upcoming models in the f * **Model comparison**: To compare model capabilities side by side, see [AUTOTITLE](/copilot/reference/ai-models/model-comparison). * **Changelog**: Model updates are announced in the [{% data variables.product.prodname_copilot_short %} changelog](https://github.blog/changelog/label/copilot/). -#### Default enablement - -{% data reusables.copilot.model-autoenablement %} - #### Special categories {% data variables.product.company_short %} categorizes certain types of model, allowing you to plan for model transitions and set user expectations. @@ -80,6 +76,12 @@ You can find information about the models available and upcoming models in the f For more information, see [AUTOTITLE](/copilot/concepts/models/utility-models) and [AUTOTITLE](/copilot/concepts/models/fallback-and-lts-models). +### Default enablement + +{% data reusables.copilot.default-availability-policies %} + +For more information, see [AUTOTITLE](/copilot/concepts/enterprise/default-availability). + ## Considering different release stages {% data variables.product.prodname_copilot_short %} features and models progress through different release stages. Understanding release stages helps you decide when to enable features for your organization. Each stage has different expectations for stability and support. diff --git a/content/copilot/concepts/enterprise/policies.md b/content/copilot/concepts/enterprise/policies.md index 4918686dbcaf..ade5bab57cee 100644 --- a/content/copilot/concepts/enterprise/policies.md +++ b/content/copilot/concepts/enterprise/policies.md @@ -40,6 +40,12 @@ A user's individual plan is cancelled when they are added to a {% data variables To see details for each policy, see [AUTOTITLE](/copilot/reference/enterprise-administrators/policy-conflicts). +## What is the default status of policies? + +{% data reusables.copilot.default-availability-policies %} + +For more information, see [AUTOTITLE](/copilot/concepts/enterprise/default-availability). + ## Where do policies apply? Policies can apply to any surface where users authenticate to {% data variables.product.prodname_copilot_short %}, including IDEs, the {% data variables.product.github %} website, and {% data variables.copilot.copilot_cli_short %}. diff --git a/content/copilot/get-started/quickstart-for-using-github-copilot-in-your-ide.md b/content/copilot/get-started/quickstart-for-using-github-copilot-in-your-ide.md index 68b350659b10..b7d7f3386b51 100644 --- a/content/copilot/get-started/quickstart-for-using-github-copilot-in-your-ide.md +++ b/content/copilot/get-started/quickstart-for-using-github-copilot-in-your-ide.md @@ -28,7 +28,7 @@ This quickstart shows you how to use these capabilities. It takes about ten minu ## Prerequisites -* **An active {% data variables.product.prodname_copilot_short %} plan.** See [AUTOTITLE](/copilot/get-started/what-is-github-copilot#get-access). +* **An active {% data variables.product.prodname_copilot_short %} plan.** See [AUTOTITLE](/copilot/get-started/about-github-copilot#get-access). * **The {% data variables.product.prodname_copilot_short %} extension for your IDE.** See [AUTOTITLE](/copilot/how-tos/set-up/install-copilot-extension). * **Signed in to {% data variables.product.company_short %} in your IDE.** If you have authentication problems, see [AUTOTITLE](/copilot/how-tos/troubleshoot-copilot/troubleshoot-common-issues). diff --git a/content/copilot/how-tos/copilot-on-github/set-up-copilot/configure-code-review.md b/content/copilot/how-tos/copilot-on-github/set-up-copilot/configure-code-review.md index 80e262f0aa45..092dd294c563 100644 --- a/content/copilot/how-tos/copilot-on-github/set-up-copilot/configure-code-review.md +++ b/content/copilot/how-tos/copilot-on-github/set-up-copilot/configure-code-review.md @@ -20,19 +20,37 @@ category: ## Introduction -You can configure {% data variables.copilot.copilot_code-review_short %} to review pull requests automatically. For an overview of automatic pull request reviews, see [AUTOTITLE](/copilot/concepts/agents/code-review#automatic-pull-request-reviews). +You can configure {% data variables.copilot.copilot_code-review_short %} to review pull requests automatically, and you can set your {% data variables.product.prodname_copilot_short %} review effort. For an overview, see [AUTOTITLE](/copilot/concepts/agents/code-review#automatic-pull-request-reviews). ## Configuring automatic code review for your own pull requests +You can set {% data variables.copilot.copilot_code-review_short %} to review the pull requests you create, in any repository where {% data variables.copilot.copilot_code-review_short %} is available to you. + > [!NOTE] -> This is only available if you are on the {% data variables.copilot.copilot_pro_short %}, {% data variables.copilot.copilot_pro_plus_short %}, or {% data variables.copilot.copilot_max_short %} plans. +> Configuring automatic code review is available on the {% data variables.copilot.copilot_pro_short %}, {% data variables.copilot.copilot_pro_plus_short %}, and {% data variables.copilot.copilot_max_short %} plans, and with a {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %} license. It is not available for {% data variables.enterprise.prodname_managed_users %}. + +{% data reusables.user-settings.copilot-settings %} +{% data reusables.copilot.code-review.user-settings-sidebar %} +1. Enable **Automatic {% data variables.copilot.copilot_code-review_short %}**. +1. Optionally, to review each new push to a pull request that {% data variables.product.prodname_copilot_short %} is already reviewing, enable **Review new pushes**. +1. Optionally, to review pull requests while they are still marked as drafts, enable **Review draft pull requests**. + +A pull request can qualify for automatic review from several independent sources: your user settings, repository rulesets, or organization rulesets. These sources are evaluated separately. If more than one source applies, {% data variables.product.prodname_copilot_short %} still posts a single review. Your user settings cannot disable push or draft reviews that a ruleset has enabled. For more information, see [AUTOTITLE](/copilot/concepts/agents/code-review#automatic-pull-request-reviews). + +## Configuring your {% data variables.product.prodname_copilot_short %} review effort -{% data reusables.copilot.your-copilot %} -1. Locate the **Automatic {% data variables.copilot.copilot_code-review_short %}** option and click the dropdown button. +You can choose the {% data variables.product.prodname_copilot_short %} review effort that {% data variables.copilot.copilot_code-review_short %} uses for the reviews you request. Your choice applies to automatic reviews and to reviews you request manually. For an overview of the levels and how {% data variables.product.prodname_copilot_short %} decides which to use, see [AUTOTITLE](/copilot/concepts/agents/code-review#review-effort-level). + +{% data reusables.user-settings.copilot-settings %} +{% data reusables.copilot.code-review.user-settings-sidebar %} +1. Next to "Review effort level," select the {% data variables.product.prodname_copilot_short %} review effort for reviews you request. + * **Lite**: Standard review. + * **Balanced**: Deeper analysis of complex logic, security-sensitive code, and cross-service changes. + * **Max**: Most thorough review. This option appears with a **Coming soon** label and is not available yet. - ![Screenshot of the "Automatic {% data variables.copilot.copilot_code-review_short %}" setting with the dropdown menu displayed.](/assets/images/help/copilot/code-review/automatic-code-review-personal.png) +To return to the built-in default, select the **Default** option at the top of the menu. Until you choose a specific level, the control shows the built-in default that applies to you, either **Default (Lite)** or **Default (Balanced)**. -1. In the dropdown menu, select **Enabled**. +Your {% data variables.product.prodname_copilot_short %} review effort is independent of **Automatic {% data variables.copilot.copilot_code-review_short %}**. Turning automatic review off does not clear your {% data variables.product.prodname_copilot_short %} review effort or stop it from applying to reviews you request manually. ## Configuring automatic code review for a repository diff --git a/content/copilot/how-tos/copilot-sdk/auth/authenticate.md b/content/copilot/how-tos/copilot-sdk/auth/authenticate.md index efd6654f5bb8..602fabaea6b1 100644 --- a/content/copilot/how-tos/copilot-sdk/auth/authenticate.md +++ b/content/copilot/how-tos/copilot-sdk/auth/authenticate.md @@ -215,6 +215,133 @@ const client = new CopilotClient({ For more information, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/github-oauth). +## Rotating session-scoped GitHub tokens + +For multi-user services and integrations, set a token provider on each session instead of storing one long-lived token. The runtime calls the provider for the effective GitHub host and identifies the request as `initial` or `refresh`. The session ID is absent only when a cloud session has not received its ID yet. + +Return a tagged token result or an explicit cancellation. Every token result must include `expiresIn`: the positive number of seconds remaining when the callback completes. Production GitHub tokens typically last eight hours, so `8 * 60 * 60` is a common value. Do not set both the static per-session token and the provider. + +{% codetabs %} +{% codetab typescript %} + + + +```typescript +const session = await client.createSession({ + gitHubTokenProvider: async ({ host, sessionId, reason }) => { + const token = await acquireGitHubToken({ host, sessionId, reason }); + return { + kind: "token", + accessToken: token.value, + expiresIn: token.secondsRemaining, + }; + }, +}); +``` + +{% endcodetab %} +{% codetab python %} + + + +```python +async def provide_github_token(args): + token = await acquire_github_token( + host=args["host"], + session_id=args["session_id"], + reason=args["reason"], + ) + return { + "kind": "token", + "accessToken": token.value, + "expiresIn": token.seconds_remaining, + } + + +session = await client.create_session(github_token_provider=provide_github_token) +``` + +{% endcodetab %} +{% codetab go %} + + + +```golang +session, err := client.CreateSession(ctx, &copilot.SessionConfig{ + GitHubTokenProvider: func(args copilot.GitHubTokenProviderArgs) (*copilot.GitHubTokenProviderResult, error) { + token, secondsRemaining, err := acquireGitHubToken(args.Host, args.SessionID, args.Reason) + if err != nil { + return nil, err + } + return copilot.GitHubTokenResult(&copilot.GitHubToken{ + AccessToken: token, + ExpiresIn: secondsRemaining, + }), nil + }, +}) +``` + +{% endcodetab %} +{% codetab dotnet %} + + + +```csharp +await using var session = await client.CreateSessionAsync(new SessionConfig +{ + GitHubTokenProvider = async args => + { + var token = await AcquireGitHubTokenAsync(args.Host, args.SessionId, args.Reason); + return GitHubTokenProviderResult.FromToken(new GitHubToken + { + AccessToken = token.Value, + ExpiresIn = token.SecondsRemaining, + }); + }, +}); +``` + +{% endcodetab %} +{% codetab java %} + + + +```java +var session = client.createSession(new SessionConfig() + .setGitHubTokenProvider(args -> + acquireGitHubToken(args.host(), args.sessionId(), args.reason()) + .thenApply(token -> GitHubTokenProviderResult.token( + token.value(), token.secondsRemaining()))) + .setOnPermissionRequest(PermissionHandler.APPROVE_ALL) +).get(); +``` + +{% endcodetab %} +{% codetab rust %} + + + +```rust +let provider = Arc::new(|args: GitHubTokenProviderArgs| async move { + let token = acquire_github_token(&args.host, args.session_id.as_ref(), args.reason).await?; + Ok(GitHubTokenProviderResult::Token(GitHubToken::new( + token.value, + token.seconds_remaining, + ))) +}); + +let session = client + .create_session(SessionConfig::default().with_github_token_provider(provider)) + .await?; +``` + +{% endcodetab %} +{% endcodetabs %} + +The runtime performs the `initial` acquisition as part of session creation or resume. A cancelled acquisition, provider error, invalid response, or token without a stable account identity rejects the create or resume operation. The runtime does not fall back to ambient authentication. + +After the session is established, the runtime performs async preflight before each credential-consuming operation. It requests a `refresh` when the current token has one hour or less remaining. Idle sessions are not refreshed until their next credential-consuming operation. The runtime does not use background timers, rejection-driven replay, 401/403 challenge propagation, or upscope for this callback. + ## Environment variables For automation, CI/CD pipelines, and server-to-server scenarios, you can authenticate using environment variables. diff --git a/content/copilot/how-tos/copilot-sdk/auth/byok.md b/content/copilot/how-tos/copilot-sdk/auth/byok.md index 6624808ec975..9c61843c1052 100644 --- a/content/copilot/how-tos/copilot-sdk/auth/byok.md +++ b/content/copilot/how-tos/copilot-sdk/auth/byok.md @@ -234,8 +234,8 @@ Anthropic models always use the Anthropic Messages API regardless of this settin **Azure (`type: "azure"`)** * Use for native Azure OpenAI endpoints -* `baseUrl` should be just the host (e.g., `https://my-resource.openai.azure.com`) -* Do NOT include `/openai/v1` in the URL—the SDK handles path construction +* `baseUrl` / `base_url` accepts a resource host or a full project URL, such as `https:///api/projects/hosted-agents-ncus`, with or without a trailing slash. +* The runtime preserves the project prefix when constructing Azure API paths. For `wireApi: "responses"` with `azure.apiVersion` omitted, the project URL above produces `https:///api/projects/hosted-agents-ncus/openai/v1/responses`. Project URLs require an updated Copilot CLI runtime. **Anthropic (`type: "anthropic"`)** * For direct Anthropic API access @@ -260,7 +260,7 @@ Use `type: "azure"` for endpoints at `*.openai.azure.com`: ```typescript provider: { type: "azure", - baseUrl: "https://my-resource.openai.azure.com", // Just the host + baseUrl: "https://my-resource.openai.azure.com", // Resource host or full project URL apiKey: process.env.AZURE_OPENAI_KEY, azure: { apiVersion: "2024-10-21", diff --git a/content/copilot/how-tos/copilot-sdk/features/client-info.md b/content/copilot/how-tos/copilot-sdk/features/client-info.md new file mode 100644 index 000000000000..9f4e932dc328 --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/features/client-info.md @@ -0,0 +1,157 @@ +--- +title: Client info +shortTitle: Client info +intro: >- + Client info identifies the application using the Copilot SDK and, when + applicable, a specific integration within it. An integration is an + identifiable sub-part of the application through which the SDK is used, such + as an extension or plugin. Set the optional `clientInfo` client option to + attribute runtime telemetry for that connection to your application instead of + the runtime's own build. +versions: + fpt: '*' + ghec: '*' +contentType: how-tos +--- + + + + +## When to set client info + +Set client info when your SDK application represents a distinct product, service, or integration whose runtime activity should be attributed consistently. + +Leave client info unset for scripts, one-off tools, and jobs that do not represent a distinct application. The runtime then keeps its default attribution. + +Client info has four optional string fields. Set the fields you know and omit the rest. The SDK includes client info in the `server.connect` handshake only when at least one field has a non-empty value. + +| Field | Example | Meaning | +|---|---|---| +| `applicationName` | `"vscode"` | Name of the application using the SDK | +| `applicationVersion` | `"1.124.2"` | Version of the application using the SDK | +| `integrationName` | `"copilot-chat"` | Name of the extension, plugin, or other application sub-part using the SDK | +| `integrationVersion` | `"0.54.0"` | Version of that extension, plugin, or application sub-part | + +For a standalone application without a distinct integration, set only the application fields. For example, a developer portal could set `applicationName` to `"acme-developer-portal"` and `applicationVersion` to `"2.4.0"`, leaving both integration fields unset. + +The SDK sends client info once when it establishes the connection. The identity applies for the lifetime of that connection. + +## Configure client info + +Pass client info when you create the client: + +{% codetabs %} +{% codetab typescript %} + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient({ + clientInfo: { + applicationName: "vscode", + applicationVersion: "1.124.2", + integrationName: "copilot-chat", + integrationVersion: "0.54.0", + }, +}); + +await client.start(); +``` + +{% endcodetab %} +{% codetab python %} + + + +```python +from copilot import CopilotClient + +client = CopilotClient( + client_info={ + "application_name": "vscode", + "application_version": "1.124.2", + "integration_name": "copilot-chat", + "integration_version": "0.54.0", + }, +) +await client.start() +``` + +{% endcodetab %} +{% codetab go %} + +```golang +client := copilot.NewClient(&copilot.ClientOptions{ + ClientInfo: &copilot.ClientInfo{ + ApplicationName: "vscode", + ApplicationVersion: "1.124.2", + IntegrationName: "copilot-chat", + IntegrationVersion: "0.54.0", + }, +}) +if err := client.Start(ctx); err != nil { + return err +} +``` + +{% endcodetab %} +{% codetab dotnet %} + +```csharp +using GitHub.Copilot; + +await using var client = new CopilotClient(new CopilotClientOptions +{ + ClientInfo = new CopilotClientInfo + { + ApplicationName = "vscode", + ApplicationVersion = "1.124.2", + IntegrationName = "copilot-chat", + IntegrationVersion = "0.54.0", + }, +}); + +await client.StartAsync(); +``` + +{% endcodetab %} +{% codetab java %} + +```java +var options = new CopilotClientOptions() + .setClientInfo(new ClientInfo() + .setApplicationName("vscode") + .setApplicationVersion("1.124.2") + .setIntegrationName("copilot-chat") + .setIntegrationVersion("0.54.0")); + +var client = new CopilotClient(options); +client.start().get(); +``` + +{% endcodetab %} +{% codetab rust %} + +```rust +use github_copilot_sdk::{Client, ClientInfo, ClientOptions}; + +let client = Client::start( + ClientOptions::new().with_client_info( + ClientInfo::new() + .with_application_name("vscode") + .with_application_version("1.124.2") + .with_integration_name("copilot-chat") + .with_integration_version("0.54.0"), + ), +) +.await?; +``` + +{% endcodetab %} +{% endcodetabs %} + +## Notes + +* Client info is advisory. The runtime can ignore values that do not match the expected format, such as an invalid version string. +* Setting client info changes how the runtime attributes its telemetry. It does not change what the runtime records. +* If every field is unset or empty, the SDK omits client info from the handshake and the runtime keeps its default attribution. diff --git a/content/copilot/how-tos/copilot-sdk/features/hooks.md b/content/copilot/how-tos/copilot-sdk/features/hooks.md index 172c78fd7633..44d381007a0e 100644 --- a/content/copilot/how-tos/copilot-sdk/features/hooks.md +++ b/content/copilot/how-tos/copilot-sdk/features/hooks.md @@ -26,13 +26,13 @@ A hook is a callback you register once when creating a session. The SDK invokes | Hook | When it fires | What you can do | | ------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------ | -| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start) | Session begins (new or resumed) | Inject context, load preferences | +| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start-hook) | Session begins (new or resumed) | Inject context, load preferences | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted) | User sends a message | Rewrite prompts, add context, filter input | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed) | Runtime builds the model prompt | Inspect or replace model-facing content | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/pre-tool-use) | Before a tool executes | Allow / deny / modify the call | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use) | After a tool returns (success only) | Transform results, redact secrets, audit | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use#failure-variant) | After a tool returns a failure | Inject retry guidance, log failures | -| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end) | Session ends | Clean up, record metrics | +| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end-hook) | Session ends | Clean up, record metrics | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling) | An error is raised | Custom logging, retry logic, alerts | All hooks are **optional**—register only the ones you need. Returning `null` (or the language equivalent) from any hook tells the SDK to continue with default behavior. diff --git a/content/copilot/how-tos/copilot-sdk/features/index.md b/content/copilot/how-tos/copilot-sdk/features/index.md index 319fb9980c9c..bcf8586f08c2 100644 --- a/content/copilot/how-tos/copilot-sdk/features/index.md +++ b/content/copilot/how-tos/copilot-sdk/features/index.md @@ -13,6 +13,7 @@ contentType: how-tos children: - /agent-loop - /citations + - /client-info - /cloud-sessions - /context-management - /custom-agents diff --git a/content/copilot/how-tos/copilot-sdk/features/plugin-directories.md b/content/copilot/how-tos/copilot-sdk/features/plugin-directories.md index 42543b900978..d7a9b68227b5 100644 --- a/content/copilot/how-tos/copilot-sdk/features/plugin-directories.md +++ b/content/copilot/how-tos/copilot-sdk/features/plugin-directories.md @@ -160,6 +160,34 @@ let client = Client::start( > The example above uses an stdio runtime connection — the default when the SDK bundles the CLI. If you connect to an external runtime via a URL (`forUri` / `ForUri`), pass `--plugin-dir` to the long-running CLI server when you start it; the SDK does not forward `--plugin-dir` to runtimes it didn't spawn. +## Per-session plugin directories + +`--plugin-dir` is a launch argument, so it fixes one plugin set for the CLI process and every session created against it. When sessions need different plugin sets, or when the SDK is connected to a runtime it did not spawn, pass the directories on the session config instead. They travel in the `session.create` and `session.resume` payloads over JSON-RPC rather than as process arguments, so they reach an external runtime the same way the startup option does. + +```typescript +import { CopilotClient } from "@github/copilot-sdk"; + +const client = new CopilotClient(); +await client.start(); + +const session = await client.createSession({ + pluginDirectories: ["./plugins/code-reviewer"], +}); +``` + +Relative paths resolve against `workingDirectory`, or the runtime working directory when that is unset, so absolute paths are recommended. Entries that do not resolve are logged and skipped rather than failing session creation. The option is an explicit opt-in, which means plugin agents and rules load even when `enableConfigDiscovery` is false. Assets loaded this way sit between project sources and personal or home sources in the session-wide precedence order. + +The equivalent option in each SDK is: + +| SDK | Session option | +|---|---| +| Node.js / TypeScript | `pluginDirectories: string[]` | +| Python | `plugin_directories=[...]` | +| Go | `PluginDirectories: []string{...}` | +| .NET | `PluginDirectories = [...]` | +| Java | `.setPluginDirectories(List.of(...))` | +| Rust | `.with_plugin_directories([...])` | + ## Trusted host-bundled plugin directories Applications that ship their own trusted plugins can register them as a client startup option. The SDK sends the complete ordered set after connecting and verifying the protocol, before `start` returns or any session can be created. Paths must be absolute; leaving the option unset or empty makes no RPC call. diff --git a/content/copilot/how-tos/copilot-sdk/features/session-persistence.md b/content/copilot/how-tos/copilot-sdk/features/session-persistence.md index 7f65427211dc..013b58ac3202 100644 --- a/content/copilot/how-tos/copilot-sdk/features/session-persistence.md +++ b/content/copilot/how-tos/copilot-sdk/features/session-persistence.md @@ -167,6 +167,8 @@ When resuming a session, you can optionally reconfigure many settings. This is u | `availableTools` | Restrict which tools are available | | `excludedTools` | Disable specific tools | | `provider` | Re-provide BYOK credentials (required for BYOK sessions) | +| `capi.autoTier` | Override the persisted Auto routing preference | +| `capi.enableWebSocketResponses` | Choose the Responses API transport for the resumed session | | `reasoningEffort` | Adjust reasoning effort level | | `streaming` | Enable/disable streaming responses | | `workingDirectory` | Change the working directory | @@ -178,6 +180,79 @@ When resuming a session, you can optionally reconfigure many settings. This is u | `disabledSkills` | Skills to disable | | `infiniteSessions` | Configure infinite session behavior | +### Auto tier persistence + +With `model: "auto"`, the optional `capi.autoTier` setting selects an Auto routing preference: `efficiency`, `balance`, `intelligence`, or `fast`. In Python, use `capi={"auto_tier": "balance"}`. This setting applies to V2 Auto routing; V1 Auto requests are unchanged. + +`fast` is an integrator-only latency preset, not a first-party GitHub Copilot product preference. The SDK does not decide Fast eligibility, inspect client identity, choose it as a default, or fall back to another tier when a runtime does not support it—an older runtime returns its native error unchanged. + +The runtime persists the selected tier, so applications do not need to resend it on every resume: + +* Omitting the tier when creating a session uses the runtime's default routing behavior. +* A cold resume restores the persisted tier. Supplying an explicit tier overrides the restored value for the new activation. +* When resuming a session already resident in the runtime, omitting the tier preserves the current selection and supplying the same tier is a no-op. Supplying a different tier requests a safe switch that the runtime applies after the resume succeeds; it cannot change a turn that is already in flight. +* Older sessions without a persisted tier retain default routing behavior. + +Tier selection is not a live model-switch operation. The SDK forwards the preference; the runtime owns persistence and validation. + +The `session.start` and `session.resume` events expose the selected tier in their optional `data.autoTier` field (`data.auto_tier` in Python). When no tier is selected, the field is omitted. + +### Changing the Auto tier during a session + +Call `setAutoTier` to change the routing preference on a live session without changing the selected model. Pass `null` (Python `None`, Go `nil`) to return to the provider's default Auto routing. + +```typescript +const result = await session.setAutoTier("intelligence"); +if (result.status === "pending") { + // Accepted, but not yet in effect. +} +``` + +The runtime does not apply the preference immediately. It records the request and commits it only when a later user turn using the `auto` model successfully obtains a usable model from the provider. A `pending` status therefore confirms that the request was accepted, not that it took effect. Only the most recent request survives: a new request replaces any earlier one that no turn has claimed yet. + +Watch for the outcome through these events: + +* `session.model_change` when the preference commits. +* `session.auto_tier_switch_failed` when it does not. This event is ephemeral, so the runtime never persists or replays it on resume. Its `reason` field is one of `policy_rejected`, `request_failed`, `setup_failed`, or `unsupported`, and the previously effective preference stays active. + +You can also read the authoritative state at any time through the session's `model.getCurrent` RPC method, which reports the committed `autoTier`, any unclaimed `pendingAutoTier`, and the `activatingAutoTier` currently claimed by an in-progress activation. + +| SDK | Change the tier | Return to provider-default routing | +|-----|-----------------|------------------------------------| +| Node.js | `session.setAutoTier("balance")` | `session.setAutoTier(null)` | +| Python | `session.set_auto_tier("balance")` | `session.set_auto_tier(None)` | +| Go | `session.SetAutoTier(ctx, &tier)` | `session.SetAutoTier(ctx, nil)` | +| .NET | `session.SetAutoTierAsync(AutoTier.Balance)` | `session.SetAutoTierAsync(null)` | +| Rust | `session.set_auto_tier(Some(AutoTier::Balance))` | `session.set_auto_tier(None)` | +| Java | `session.setAutoTier(AutoTier.BALANCE)` | `session.setAutoTier(null)` | + +To select the `auto` model and its routing preference in a single call, stage the tier on the model switch instead. The runtime rejects this option when the model is anything other than `auto`. + +| SDK | Stage a tier with the switch | Reset to provider-default routing | +|-----|------------------------------|-----------------------------------| +| Node.js | `setModel("auto", { autoTier: "balance" })` | `setModel("auto", { autoTier: null })` | +| Python | `set_model("auto", auto_tier="balance")` | `set_model("auto", auto_tier=None)` | +| Go | `SetModelOptions{AutoTier: &tier}` | `SetModelOptions{ResetAutoTier: true}` | +| .NET | `new SetModelOptions { AutoTier = AutoTier.Balance }` | `new SetModelOptions { ResetAutoTier = true }` | +| Rust | `SetModelOptions::default().with_auto_tier(AutoTier::Balance)` | `SetModelOptions::default().with_reset_auto_tier()` | +| Java | `new SetModelOptions().setModel("auto").setAutoTier(AutoTier.BALANCE)` | `new SetModelOptions().setModel("auto").setResetAutoTier(true)` | + +Node.js, Python, and Rust express all three states in a single value: Node.js and Python because `null`/`None` is distinguishable from an omitted argument, and Rust because `AutoTierPreference::Reset` is a distinct variant of the same option. Go, .NET, and Java have no way to distinguish "reset" from "unset" in one value, so they carry a separate reset flag. Omitting both always means "leave the current preference alone." + +### Responses transport on resume + +The optional `capi.enableWebSocketResponses` setting chooses the transport for the CAPI Responses API. It defaults to `true`, so the WebSocket transport is used whenever the selected model advertises the `ws:/responses` endpoint. Setting it to `false` falls back to the HTTP transport. In Python, use `capi={"enable_web_socket_responses": False}`. + +Supply it on the resume call when you need it. It is worth setting when WebSocket connections fail behind a proxy, and when a resumed session reports `400 input item ID does not belong to this connection`, which is specific to the WebSocket transport. + +```typescript +const session = await client.resumeSession("user-123-task-456", { + capi: { enableWebSocketResponses: false }, +}); +``` + +Setting this to `false` is equivalent to the `COPILOT_CLI_DISABLE_WEBSOCKET_RESPONSES` environment variable, which has the opposite polarity. + ### Example: changing model on resume ```typescript diff --git a/content/copilot/how-tos/copilot-sdk/features/skills.md b/content/copilot/how-tos/copilot-sdk/features/skills.md index 71fa9121dc63..cf1bc42374aa 100644 --- a/content/copilot/how-tos/copilot-sdk/features/skills.md +++ b/content/copilot/how-tos/copilot-sdk/features/skills.md @@ -303,6 +303,22 @@ The markdown body contains the instructions that are injected into the session c | .NET | `SkillDirectories` | `List` | Directories to load skills from | | .NET | `DisabledSkills` | `List` | Skills to disable | +### Built-in skills and `mode: "empty"` + +The runtime ships with a set of bundled **built-in** skills that are eligible by +default. When you run the client in `mode: "empty"` (the recommended baseline for +[AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/multi-tenancy)), the SDK excludes every +runtime-bundled built-in skill: it sends an empty `includedBuiltinSkills` list on +the post-create and post-resume options patch, alongside the empty +`installedPlugins` list. + +This exclusion is the default, not a permanent restriction. To allow selected +runtime-bundled skills, set `includedBuiltinSkills` (or the language-specific +casing) to their names. You can also opt into your **own** custom skills under +`mode: "empty"`—enable skills and pass your own `skillDirectories`—and those +remain fully usable, including a custom skill that shares a name with a built-in. +Under `mode: "copilot-cli"` the field is omitted unless you set the option. + ## Best practices 1. **Organize by domain** - Group related skills together (e.g., `skills/security/`, `skills/testing/`) diff --git a/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md b/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md index 3669f9c5c2ca..7ea61b75539e 100644 --- a/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md +++ b/content/copilot/how-tos/copilot-sdk/features/steering-and-queueing.md @@ -27,6 +27,28 @@ When a session is actively processing a turn, incoming messages can be delivered ![Diagram: Sequence diagram showing the described process.](/assets/images/help/copilot/copilot-sdk/features-steering-and-queueing-diagram-0.png) +## Message provenance + +Set the optional source when forwarding a message from another agent. An identified agent source serializes as `agent-`. Leave source unset for ordinary human sends to preserve runtime defaults. Both send and send-and-wait APIs support source with `"enqueue"` and `"immediate"` delivery. + +| SDK | Identified agent source | +|-----|-------------------------| +| Node.js / TypeScript | `source: "agent-sender-id"` | +| Python | `source=AgentMessageSource("sender-id")` | +| Go | `Source: copilot.MessageSourceAgent("sender-id")` | +| .NET | `Source = MessageSource.Agent("sender-id")` | +| Java | `.setSource(MessageSource.agent("sender-id"))` | +| Rust | `.with_source(MessageSource::Agent("sender-id".into()))` | + +The typed APIs also support `user` and `system`. Use `system` for internal application context, not as a substitute for an identified agent. Agent provenance lets the runtime distinguish agent input from human authorization while retaining its agent-message steering behavior. Derive the sender ID from trusted application metadata, never from message text. + +Source identifies origin. Delivery mode requests urgency. Neither requires the recipient to produce a visible reply, and source does not set billing flags. The runtime applies its existing scheduling rules. Rust callers using the typed RPC API can also pass `MessageSource` to `rpc::SendRequest::with_source(...)`. + +A successful high-level `send` acknowledgement returns a message ID and confirms acceptance, not that the recipient has consumed the message. Do not automatically resend an accepted message merely because no reply appears. Send-and-wait can complete on an idle event without an assistant message. + +> [!WARNING] +> Remote backends do not necessarily preserve source end to end. The agent session can include source in its local echo without carrying it in the remote HTTP request. A local source event does not prove that the remote worker received the same provenance. + ## Steering (immediate mode) Steering sends a message that is injected directly into the agent's current turn. The agent sees the message in real time and adjusts its response accordingly—useful for course-correcting without aborting the turn. diff --git a/content/copilot/how-tos/copilot-sdk/features/streaming-events.md b/content/copilot/how-tos/copilot-sdk/features/streaming-events.md index 47e136e34e88..40df8147cd41 100644 --- a/content/copilot/how-tos/copilot-sdk/features/streaming-events.md +++ b/content/copilot/how-tos/copilot-sdk/features/streaming-events.md @@ -125,6 +125,48 @@ session.on(AssistantMessageDeltaEvent.class, event -> > [!TIP] > **(TypeScript)** The TypeScript SDK uses a discriminated union—when you match on `event.type`, the `data` payload is automatically narrowed to the correct shape. +## Subscribing before a session starts + +A session can emit events before its create or resume call returns. The agent may already be working—especially on resume with `continuePendingWork`—and ephemeral events such as `session.idle` are never written to the session log, so `getMessages` cannot recover them afterwards. A subscription installed after the session handle exists misses that startup window. + +> [!TIP] +> **(Rust)** `Client::prepare_session` and `Client::prepare_resume_session` return a `PreparedSession` that owns the session's event channel before any protocol activity happens. Subscribe first, then call `start()`. + +```rust +use github_copilot_sdk::{Client, SessionConfig}; + +async fn create_without_missing_startup_events( + client: &Client, +) -> Result<(), github_copilot_sdk::Error> { + let prepared = client.prepare_session( + SessionConfig::default().with_event_buffer_capacity(2048), + )?; + + // Installed before any wire activity: nothing is dropped for lack of a receiver. + let mut events = prepared.subscribe(); + tokio::spawn(async move { + while let Ok(event) = events.recv().await { + println!("{}", event.event_type); + } + }); + + let session = prepared.start().await?; + let _ = session; + Ok(()) +} +``` + +`prepare_*` is synchronous and inert: it validates the buffer capacity, allocates a local channel, and does nothing else. No session is registered and nothing reaches the CLI until `start()` is first polled. Dropping a prepared session that was never started leaves no state behind and closes its subscriptions; dropping the `start()` future cancels the in-flight startup and unregisters the session, so a retry with the same session ID succeeds. Cleanup is scoped to the exact registration the abandoned startup owned, so it cannot evict a retry that has already taken over the same session ID. + +Startup buffering is worth planning for: + +* The event buffer is finite—512 events unless `event_buffer_capacity` overrides it. A capacity of `0` is rejected with an invalid-config error rather than clamped. +* Slow subscribers observe a `Lagged` error reporting how many events were skipped. They never apply backpressure to the session's event loop. +* Consumers that need a lossless view of a large startup burst must either configure a capacity that covers it or drain the subscription concurrently with `start()`. + +> [!NOTE] +> For cloud sessions where the server assigns the session ID, the SDK cannot route notifications until the create response arrives and the ID is known. Events emitted before that point are not routable to any session. The guarantee is narrower: routed events are never dropped for lack of an installed receiver. Pin `session_id` on the config to get routing—and full pre-response coverage—from the first byte. + ## Render only the parent agent response Sub-agent events share the parent session stream and include envelope-level `agentId`. Root/main agent events and session-level events omit `agentId`, so main-chat renderers can ignore assistant events where `agentId` is set and route those events to traces or progress UI instead. diff --git a/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md b/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md index 58541e6eeb89..f9dfe320ff4d 100644 --- a/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md +++ b/content/copilot/how-tos/copilot-sdk/hooks/hooks-overview.md @@ -30,10 +30,10 @@ contentType: how-tos | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/post-tool-use#failure-variant) | After a tool execution whose result was a failure | Inject retry guidance, log failures | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted) | When user sends a message | Prompt modification, filtering | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed) | After runtime prompt transformation | Inspect or replace model-facing content | -| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start) | Session begins | Add context, configure session | -| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end) | Session ends | Cleanup, analytics | +| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-start-hook) | Session begins | Add context, configure session | +| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#session-end-hook) | Session ends | Cleanup, analytics | | [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling) | Error happens | Custom error handling | -| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#agent-stop) | Top-level agent naturally stops | Validate completion or request another turn | +| [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#agent-stop-hook) | Top-level agent naturally stops | Validate completion or request another turn | ## Quick start @@ -272,7 +272,7 @@ const session = await client.createSession({ * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-submitted)** - Modify user prompts * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/user-prompt-transformed)** - Replace model-facing prompts * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle)** - Session start and end -* **[AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#agent-stop)** - Validate completion before the agent stops +* **[AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle#agent-stop-hook)** - Validate completion before the agent stops * **[AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/error-handling)** - Custom error handling ## See also diff --git a/content/copilot/how-tos/copilot-sdk/hooks/session-lifecycle.md b/content/copilot/how-tos/copilot-sdk/hooks/session-lifecycle.md index ff8d463f6e73..fa73a3bd9f4b 100644 --- a/content/copilot/how-tos/copilot-sdk/hooks/session-lifecycle.md +++ b/content/copilot/how-tos/copilot-sdk/hooks/session-lifecycle.md @@ -20,8 +20,6 @@ contentType: how-tos * Track session metrics and analytics * Configure session behavior dynamically - - ## Session start hook The `onSessionStart` hook is called when a session begins (new or resumed). @@ -202,8 +200,6 @@ const session = await client.createSession({ }); ``` - - ## Session end hook The `onSessionEnd` hook is called when a session ends. @@ -449,8 +445,6 @@ Session Summary: }); ``` - - ## Agent stop hook The agent stop hook runs when the top-level agent naturally reaches the end of a turn. It is separate from `onSessionEnd`: the session remains active, and the hook can request another agent turn. diff --git a/content/copilot/how-tos/copilot-sdk/setup/backend-services.md b/content/copilot/how-tos/copilot-sdk/setup/backend-services.md index a70cdf76553f..c7024572bfa9 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/backend-services.md +++ b/content/copilot/how-tos/copilot-sdk/setup/backend-services.md @@ -417,7 +417,7 @@ setInterval(() => cleanupSessions(24 * 60 * 60 * 1000), 60 * 60 * 1000); | **Single CLI server = single point of failure** | See [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/scaling) for HA patterns | | **No built-in auth between SDK and CLI** | Secure the network path (same host, VPC, etc.) | | **Session state on local disk** | Mount persistent storage for container restarts | -| **30-minute idle timeout** | Sessions without activity are auto-cleaned | +| **No idle timeout by default** | Pass `--session-idle-timeout ` to the CLI server to automatically clean up inactive sessions | ## When to move on diff --git a/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md b/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md index 51076cb21120..1042adc6cb6a 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md +++ b/content/copilot/how-tos/copilot-sdk/setup/bundled-cli.md @@ -40,6 +40,9 @@ When you install the SDK, the Copilot runtime is included automatically (Node.js ## Quick start +> [!NOTE] +> Each SDK has a minimum language runtime requirement—see the Prerequisites section of the [Node.js](https://github.com/github/copilot-sdk/tree/main/nodejs/README.md#prerequisites), [Python](https://github.com/github/copilot-sdk/tree/main/python/README.md#prerequisites), [Go](https://github.com/github/copilot-sdk/tree/main/go/README.md#prerequisites), [Rust](https://github.com/github/copilot-sdk/tree/main/rust/README.md#prerequisites), [Java](https://github.com/github/copilot-sdk/tree/main/java/README.md#prerequisites), or [.NET](https://github.com/github/copilot-sdk/tree/main/dotnet/README.md#prerequisites) README—since an unsupported runtime (e.g. Python below the stated floor) can cause `pip`/package managers to silently resolve an outdated SDK release instead of reporting a version conflict. + {% codetabs %} {% codetab typescript %} diff --git a/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md b/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md index 34c16e7d36cd..9b0ef338e28f 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md +++ b/content/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path.md @@ -84,6 +84,7 @@ Use this table to find the right guides based on what you need to do: | Use your own model keys (OpenAI, Azure, and more) | [AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/byok) | | Azure BYOK with Managed Identity (no API keys) | [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/azure-managed-identity) | | Run the SDK on a server | [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/backend-services) | +| Host the runtime inside your application process (no separate CLI process) | [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/in-process-runtime) *(experimental)* | | Configure SDK options for concurrent users | [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/multi-tenancy) | | Serve multiple users / scale horizontally | [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/scaling) | diff --git a/content/copilot/how-tos/copilot-sdk/setup/in-process-runtime.md b/content/copilot/how-tos/copilot-sdk/setup/in-process-runtime.md new file mode 100644 index 000000000000..5d5c50f5bc3b --- /dev/null +++ b/content/copilot/how-tos/copilot-sdk/setup/in-process-runtime.md @@ -0,0 +1,223 @@ +--- +title: Run the Copilot runtime in process +shortTitle: In-process runtime +intro: >- + In-process hosting loads the native Copilot runtime into your application + process instead of starting a separate Copilot CLI process. Use it to remove + child-process management while keeping the same Copilot SDK sessions, events, + tools, hooks, and JSON-RPC behavior. +versions: + fpt: '*' + ghec: '*' +contentType: how-tos +--- + + + + +> [!WARNING] +> In-process hosting is experimental in every SDK. Test startup, model turns, and shutdown behavior on every operating system and architecture that you deploy. + +## When to use in-process hosting + +In-process hosting is a good fit when: + +* Your application must run without a separate runtime process. +* You want the SDK to own the runtime lifecycle. +* You can ship a native library for each deployment platform. +* Process-wide environment and working-directory settings are acceptable. + +Use the [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/bundled-cli) when process isolation and the most established deployment path are more important. Use a [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/backend-services) when multiple application instances must connect to a shared runtime over TCP. + +## How it works + +The SDK loads the Copilot runtime native library and binds its fixed C ABI. All SDK methods continue to use the existing `Content-Length`-framed JSON-RPC protocol over an in-memory connection. + +![Diagram: Flowchart showing the described process.](/assets/images/help/copilot/copilot-sdk/setup-in-process-runtime-diagram-0.png) + +The runtime: + +* Runs in the application process without Node.js, a child process, a TCP port, or a connection token. +* Supports the same sessions, streaming events, tools, hooks, permissions, and server-to-client requests as other transports. +* Can invoke SDK callbacks from native worker threads. The SDK handles thread marshalling and callback lifetime. +* Keeps the loaded native library and its worker pool available for the lifetime of the application process. + +## SDK requirements + +All SDKs expose an explicit in-process connection option. Some languages require additional build or package configuration. + +| SDK | Connection option | Additional requirement | +|-----|-------------------|------------------------| +| TypeScript | `RuntimeConnection.forInProcess()` | None when the package includes a compatible runtime bundle | +| Python | `RuntimeConnection.for_inprocess()` | Pre-download with `python -m copilot download-runtime --in-process` when runtime download is unavailable during startup | +| Go | `copilot.InProcessConnection{}` | Build with `-tags copilot_inprocess` | +| .NET | `RuntimeConnection.ForInProcess()` | Allow the `GHCP001` experimental API diagnostic | +| Rust | `Transport::InProcess` | Enable the `bundled-in-process` Cargo feature | +| Java | `RuntimeConnection.forInProcess()` | Add JNA, a platform runtime classifier, and experimental API opt-in | + +The native runtime bundle must match the host operating system, CPU architecture, and, on Linux, C library. Unsupported hosts fail during runtime resolution or startup instead of falling back to a child process. + +## Configure an in-process connection + +Pass the language-specific connection option when you create the client. + +{% codetabs %} +{% codetab typescript %} + + + +```typescript +import { CopilotClient, RuntimeConnection } from "@github/copilot-sdk"; + +const client = new CopilotClient({ + connection: RuntimeConnection.forInProcess(), +}); + +await client.start(); +``` + +{% endcodetab %} +{% codetab python %} + + + +```python +from copilot import CopilotClient, RuntimeConnection + +client = CopilotClient( + connection=RuntimeConnection.for_inprocess(), +) + +await client.start() +``` + +{% endcodetab %} +{% codetab go %} + + + +```golang +client := copilot.NewClient(&copilot.ClientOptions{ + Connection: copilot.InProcessConnection{}, +}) + +if err := client.Start(context.Background()); err != nil { + log.Fatal(err) +} +defer client.Stop() +``` + +{% endcodetab %} +{% codetab dotnet %} + + + +```csharp +#pragma warning disable GHCP001 + +var client = new CopilotClient(new CopilotClientOptions +{ + Connection = RuntimeConnection.ForInProcess(), +}); + +await client.StartAsync(); +``` + +{% endcodetab %} +{% codetab rust %} + + + +```rust +let options = ClientOptions::default() + .with_transport(Transport::InProcess); + +let client = Client::start(options).await?; +``` + +{% endcodetab %} +{% codetab java %} + + + +```java +import com.github.copilot.AllowCopilotExperimental; + +@AllowCopilotExperimental +public class Example { + public void run() throws Exception { + CopilotClientOptions options = new CopilotClientOptions() + .setConnection(RuntimeConnection.forInProcess()); + + CopilotClient client = new CopilotClient(options); + client.start().join(); + } +} +``` + +`RuntimeConnection.forInProcess()` is `@CopilotExperimental`, so the consuming class or method must opt in with `@AllowCopilotExperimental` (or compile with `-Acopilot.experimental.allowed=true`). See [Using experimental APIs](https://github.com/github/copilot-sdk/tree/main/java/README.md#using-experimental-apis). + +{% endcodetab %} +{% endcodetabs %} + +You can also set `COPILOT_SDK_DEFAULT_CONNECTION=inprocess` before starting the application. The SDK uses this value only when the client does not specify a connection explicitly. An invalid value causes startup to fail. + +Prefer explicit client configuration in application code. Use the environment variable when deployment configuration must select the transport without changing the application. + +## Configure the runtime + +The SDK converts supported typed client options into native runtime arguments and host-scoped environment values. Depending on the SDK, these options include: + +* Authentication token and logged-in-user fallback. +* Copilot base directory. +* Log level. +* Session idle timeout. +* Remote session mode. + +The in-process runtime receives a snapshot of the host environment plus supported SDK-managed overrides. It does not mutate the host environment. + +Set process-wide values before creating the first in-process client. This includes environment variables that are not represented by typed client options and the application's current working directory. + +## Runtime library resolution + +Each SDK first looks for a compatible bundled or cached runtime library. You can set `COPILOT_CLI_PATH` to point into a compatible Copilot runtime package when you need to provide the runtime separately. + +Only one native runtime library path and version can normally be loaded in a process. Starting another client with the same loaded library is supported, but attempting to load a different runtime library fails. + +For production deployments: + +1. Build and test the application for each target platform. +1. Ensure that the matching native runtime artifact is included in the deployed package or available through the SDK's runtime download mechanism. +1. Start at least one session and complete a model turn in a deployment smoke test. +1. Stop clients gracefully before the application exits. + +## Lifecycle behavior + +Starting an in-process client loads the native library, creates a runtime host, opens an in-memory connection, and performs the normal SDK protocol-version handshake. + +During graceful shutdown, the SDK: + +1. Closes active sessions. +1. Requests normal runtime shutdown over JSON-RPC. +1. Closes the JSON-RPC and native connections. +1. Releases the runtime host. + +The native library can remain loaded until the application process exits. Do not depend on unloading and replacing the runtime library after first use. + +## Limitations + +In-process hosting has these current constraints: + +* **Experimental API**: behavior and packaging requirements can change between releases. +* **Shared process state**: all clients share the host process environment, current working directory, native library, and runtime worker pool. +* **Restricted process options**: SDK options for an arbitrary environment, working directory, telemetry configuration, executable path, or CLI arguments are rejected where applicable. Configure process-global values on the host process and use supported typed options for runtime settings. +* **No per-client working directory**: the runtime uses the hosting process working directory. +* **One runtime version per process**: loading another native library path or version is not supported. +* **Platform maturity varies**: some SDK and platform combinations have reduced model-turn or shutdown coverage. Validate the exact combination that you deploy. + +## Further reading + +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/choosing-a-setup-path): compare in-process hosting with other deployment models +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/bundled-cli): run the bundled runtime in a managed child process +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/backend-services): connect applications to a shared runtime over TCP +* [AUTOTITLE](/copilot/how-tos/copilot-sdk/hooks/session-lifecycle): handle session start and end events diff --git a/content/copilot/how-tos/copilot-sdk/setup/index.md b/content/copilot/how-tos/copilot-sdk/setup/index.md index 1766006906b2..ebaa7049205e 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/index.md +++ b/content/copilot/how-tos/copilot-sdk/setup/index.md @@ -13,6 +13,7 @@ children: - /bundled-cli - /choosing-a-setup-path - /github-oauth + - /in-process-runtime - /local-cli - /multi-tenancy - /scaling diff --git a/content/copilot/how-tos/copilot-sdk/setup/multi-tenancy.md b/content/copilot/how-tos/copilot-sdk/setup/multi-tenancy.md index b2fda09f2a99..30d968fbfcbd 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/multi-tenancy.md +++ b/content/copilot/how-tos/copilot-sdk/setup/multi-tenancy.md @@ -39,7 +39,9 @@ This guide is a sister to [AUTOTITLE](/copilot/how-tos/copilot-sdk/setup/scaling | `baseDirectory` | Isolating `COPILOT_HOME` per runtime instance | Ignored when connecting to an existing runtime. | | `sessionFs` | Routing session filesystem storage off local disk | Pair with per-session filesystem providers. | | `RuntimeConnection.forUri(url)` | Sharing one already-running runtime | Language names vary; see samples below. | -| Per-session `gitHubToken` | Scoping auth to the requesting user | Prefer this over a single shared user token. | +| Per-session GitHub token or provider | Scoping auth to the requesting user | Prefer a rotating provider for short-lived credentials; use a static `gitHubToken` only when rotation is unnecessary. | + +For callback-backed credentials, see [AUTOTITLE](/copilot/how-tos/copilot-sdk/auth/authenticate#rotating-session-scoped-github-tokens). Each session owns its provider registration, so concurrent sessions can use different GitHub hosts and accounts without sharing callback state. ### `mode: "empty"` @@ -299,10 +301,13 @@ Session-level isolation means the runtime keeps user-specific model and state in | Session state | Per session ID under `COPILOT_HOME/session-state/{sessionId}`. | | GitHub identity | Per-session when `gitHubToken` is set on the session. | | Tools | Explicit in `mode: "empty"`; ambient in `mode: "copilot-cli"`. | +| Skills | In `mode: "empty"` no runtime-bundled built-in skills are eligible by default; callers can allow selected built-ins or opt into their own custom skills. Ambient in `mode: "copilot-cli"`. | | Host filesystem | Shared by the runtime process if host tools are available. | `mode: "empty"` is what makes shared runtime patterns viable: no ambient OS tools are exposed unless your application registers or allows them. With `mode: "copilot-cli"`, OS filesystem access is shared through the host process, so do not use that mode for multi-user server mode. +Under `mode: "empty"` the SDK excludes every runtime-bundled built-in skill by default (it sends an empty `includedBuiltinSkills` list on the post-create/post-resume options patch, alongside the empty `installedPlugins` list). Set `includedBuiltinSkills` (or the language-specific casing) to explicitly allow selected built-ins, just as `availableTools` allows selected runtime-bundled tools. A caller can also opt into its **own** custom skills—for example by enabling skills and pointing at its own skill directories—and those remain usable. + Session state is stored under `COPILOT_HOME/session-state/{sessionId}` unless you route it through `sessionFs`. Use unique session IDs that include your own tenant or user boundary, and enforce access control before resuming or deleting sessions. ## Pattern comparison diff --git a/content/copilot/how-tos/copilot-sdk/setup/scaling.md b/content/copilot/how-tos/copilot-sdk/setup/scaling.md index c74fc90b6fb6..10474bdf13e9 100644 --- a/content/copilot/how-tos/copilot-sdk/setup/scaling.md +++ b/content/copilot/how-tos/copilot-sdk/setup/scaling.md @@ -444,7 +444,7 @@ volumes: | **No built-in session locking** | Implement application-level locking for concurrent access | | **No built-in load balancing** | Use external LB or service mesh | | **Session state is file-based** | Requires shared filesystem for multi-server setups | -| **30-minute idle timeout** | Sessions without activity are auto-cleaned by the CLI | +| **No idle timeout by default** | Pass `--session-idle-timeout ` to the CLI server to automatically clean up inactive sessions | | **CLI is single-process** | Scale by adding more CLI server instances, not threads | ## Next steps diff --git a/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md b/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md index 4c2d03f0dd06..70178632a802 100644 --- a/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md +++ b/content/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review.md @@ -85,7 +85,7 @@ With review effort levels, you can choose the level of thoroughness of {% data v * **Lite**: Cost-efficient review that provides targeted feedback on glaring issues such as bugs, security vulnerabilities, and style inconsistencies. * **Balanced**: Deeper analysis of complex logic, security-sensitive code, and cross-service changes, using a higher-reasoning model. -You can select the review effort level in the pull request before you request a review from {% data variables.product.prodname_copilot_short %}, under the **Reviewers** section where {% data variables.product.prodname_copilot_short %} appears as a reviewer. Organization owners and repository administrators can also set a default effort level for automatic reviews. +You can select {% data variables.product.prodname_copilot_short %} review effort in the pull request before you request a review from {% data variables.product.prodname_copilot_short %}, under the **Reviewers** section where {% data variables.product.prodname_copilot_short %} appears as a reviewer. You can also set a default {% data variables.product.prodname_copilot_short %} review effort in your settings. Organization owners and repository administrators can set a default {% data variables.product.prodname_copilot_short %} review effort for automatic reviews. For more information, see [AUTOTITLE](/copilot/concepts/agents/code-review#review-effort-level). diff --git a/content/copilot/tutorials/roll-out-at-scale/govern-at-scale/govern-for-adoption.md b/content/copilot/tutorials/roll-out-at-scale/govern-at-scale/govern-for-adoption.md index 303d0d0b08f1..b2f1f15c1924 100644 --- a/content/copilot/tutorials/roll-out-at-scale/govern-at-scale/govern-for-adoption.md +++ b/content/copilot/tutorials/roll-out-at-scale/govern-at-scale/govern-for-adoption.md @@ -34,10 +34,12 @@ Developers get the most value from {% data variables.product.prodname_copilot_sh Consider enabling vetted capabilities promptly, rather than disabling features by default and enabling them only after review: * **Enable new features as they become available**, unless you have a specific compliance reason not to. {% data variables.product.github %} vets all features and models before release. -* **Enable new models automatically**. By default, most new generally available models are enabled automatically. We recommend keeping the **Default availability for released models** policy enabled and only explicitly disabling individual models that you do not want to be available. +* **Enable new models automatically**. By default, most new generally available models are enabled automatically. * **Only set enterprise-level defaults to disabled for non-negotiables**, such as compliance-critical controls or features that conflict with regulatory requirements. * **Scope restrictions to sensitive organizations**. Rather than blocking features enterprise-wide, disable them only in organizations with stricter compliance requirements. This lets other organizations move faster. +We recommend keeping the default availability policies enabled for both features and models, and only explicitly disabling individual features and models that you do not want to be available. See [AUTOTITLE](/copilot/concepts/enterprise/default-availability). + ### Spend management and policy posture Spend controls interact with your policies. If you enable advanced models and agentic features but set tight budget limits, developers may not be able to use those features consistently. diff --git a/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md b/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md index 59459bce8f6d..d8235c1698d3 100644 --- a/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md +++ b/content/organizations/managing-peoples-access-to-your-organization-with-roles/permissions-of-custom-organization-roles.md @@ -81,7 +81,7 @@ Organization permissions do not grant read, write, or administrator access to an | View {% data variables.product.prodname_dependabot %} alert dismissal requests | View {% data variables.product.prodname_dependabot %} alert dismissal requests for your organization. | [AUTOTITLE](/code-security/how-tos/manage-security-alerts/manage-dependabot-alerts/enable-delegated-alert-dismissal) | | {% endif %} | | {% ifversion copilot %} | -| View organization {% data variables.product.prodname_copilot_short %} metrics | View {% data variables.product.prodname_copilot_short %} usage metrics for your organization. | [AUTOTITLE](/copilot/concepts/copilot-usage-metrics/copilot-metrics) | +| View organization {% data variables.product.prodname_copilot_short %} metrics | View {% data variables.product.prodname_copilot_short %} usage metrics for your organization. | [AUTOTITLE](/copilot/concepts/billing-and-usage/copilot-usage-metrics/copilot-metrics) | | {% endif %} | {% endrowheaders %} diff --git a/data/features/proof-of-presence.yml b/data/features/proof-of-presence.yml new file mode 100644 index 000000000000..41ccdeff24f5 --- /dev/null +++ b/data/features/proof-of-presence.yml @@ -0,0 +1,4 @@ +# Proof of Presence for enterprise sudo actions. +versions: + ghec: '*' + ghes: '>=3.23' diff --git a/data/reusables/actions/changing-workflow-access-for-a-runner-group.md b/data/reusables/actions/changing-workflow-access-for-a-runner-group.md index 3c6e36d74a20..1c68770e91af 100644 --- a/data/reusables/actions/changing-workflow-access-for-a-runner-group.md +++ b/data/reusables/actions/changing-workflow-access-for-a-runner-group.md @@ -9,7 +9,7 @@ Always include a security admonition above this procedure. This is either one of {% data reusables.actions.settings-sidebar-actions-runner-groups-selection %} 1. Under **Workflow access**, select the dropdown menu and click **Selected workflows**. 1. Click {% octicon "gear" aria-label="the gear icon" %}. -1. Enter a comma separated list of the workflows that can access the runner group. Use the full path, including the repository name and owner. Pin the workflow to a branch, tag, or full SHA. For example: `octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main`. +1. Enter a comma separated list of the workflows that can access the runner group. Use the full path, including the repository name and owner. Pin non-reusable workflows to a branch. Pin reusable workflows to a branch, tag, or full SHA. For example: `octo-org/octo-repo/.github/workflows/build.yml@v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@main`. Only jobs directly defined within the selected workflows will have access to the runner group. diff --git a/data/reusables/actions/runner-group-assign-policy-workflow.md b/data/reusables/actions/runner-group-assign-policy-workflow.md index ba943d114bd7..b0b43bbf55a9 100644 --- a/data/reusables/actions/runner-group-assign-policy-workflow.md +++ b/data/reusables/actions/runner-group-assign-policy-workflow.md @@ -1,7 +1,7 @@ {%- ifversion ghec or ghes %} 1. Assign a policy for workflow access. - You can configure a runner group to be accessible to a specific list of workflows, or to all workflows. This setting can't be overridden if you are configuring an organization's runner group that was shared by an enterprise. If you specify what workflow can access the runner group, you must use the full path to the workflow, including the repository name and owner, and you must pin the workflow to a branch, tag, or full SHA. For example: `octo-org/octo-repo/.github/workflows/build.yml@refs/tags/v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@refs/heads/main`. + You can configure a runner group to be accessible to a specific list of workflows, or to all workflows. This setting can't be overridden if you are configuring an organization's runner group that was shared by an enterprise. If you specify what workflows can access the runner group, use the full path to the workflow, including the repository name and owner. Pin non-reusable workflows to a branch. Pin reusable workflows to a branch, tag, or full SHA. For example: `octo-org/octo-repo/.github/workflows/build.yml@refs/tags/v2, octo-org/octo-repo/.github/workflows/deploy.yml@d6dc6c96df4f32fa27b039f2084f576ed2c5c2a5, monalisa/octo-test/.github/workflows/test.yml@refs/heads/main`. It is best practice to fully qualify ambiguous refs. For example, instead of providing `main` as a ref, provide `refs/heads/main`. diff --git a/data/reusables/copilot/code-review/user-settings-sidebar.md b/data/reusables/copilot/code-review/user-settings-sidebar.md new file mode 100644 index 000000000000..a271f961d218 --- /dev/null +++ b/data/reusables/copilot/code-review/user-settings-sidebar.md @@ -0,0 +1 @@ +1. In the sidebar, under **{% octicon "copilot" aria-hidden="true" aria-label="copilot" %} {% data variables.product.prodname_copilot_short %}**, click **Code review**. diff --git a/data/reusables/copilot/default-availability-policies.md b/data/reusables/copilot/default-availability-policies.md new file mode 100644 index 000000000000..f6c55c3d9de7 --- /dev/null +++ b/data/reusables/copilot/default-availability-policies.md @@ -0,0 +1,7 @@ +For enterprises with {% data variables.copilot.copilot_business_short %} or {% data variables.copilot.copilot_enterprise_short %} plans, two separate policies control whether unconfigured generally available (GA) features and models default to enabled or disabled. If these policies are enabled, users benefit from the latest features and models without the need for administrator intervention. + + + +The models policy is already active. The feature policy will become active soon. + + diff --git a/data/reusables/enterprise-accounts/proof-of-presence-supported-idps.md b/data/reusables/enterprise-accounts/proof-of-presence-supported-idps.md new file mode 100644 index 000000000000..b5070cdc9d30 --- /dev/null +++ b/data/reusables/enterprise-accounts/proof-of-presence-supported-idps.md @@ -0,0 +1 @@ +During public preview, Proof of Presence supports **Microsoft Entra ID**. \ No newline at end of file diff --git a/src/codeql-cli/README.md b/src/codeql-cli/README.md index c4ea4e9130c4..dac5c28c25ba 100644 --- a/src/codeql-cli/README.md +++ b/src/codeql-cli/README.md @@ -30,7 +30,7 @@ To run the CodeQL CLI pipeline locally: ## Content team -The content writers can manually update parts of the autogenerated Markdown files in `content/code-security/codeql-cli/codeql-cli-manual`. When new Markdown files are added they will get all of the frontmatter properties defined in the `defaultFrontmatter` property in `src/codeql-cli/lib/config.ts`. +The content writers can manually update parts of the autogenerated Markdown files in `content/code-security/codeql-cli/codeql-cli-manual`. When new Markdown files are added they will get all of the frontmatter properties defined in the `defaultFrontmatter` property in `src/codeql-cli/lib/config.json`. When a new Markdown file is created, a writer can manually change any of the frontmatter. The pipeline will not overwrite the frontmatter on subsequent runs. diff --git a/src/codeql-queries/README.md b/src/codeql-queries/README.md index 07373666ac96..c7297459ecce 100644 --- a/src/codeql-queries/README.md +++ b/src/codeql-queries/README.md @@ -54,7 +54,7 @@ accDescr: A flow chart describing how the automation generates documentation for class security-markdown,quality-markdown,security-suites,quality-suites,codeql-cli file; ``` -A [workflow](../../.github/workflows/generate-codeql-query-lists.yml) is used to trigger the automation of the CodeQL query tables documentation. The workflow is manually triggered by a member of the GitHub Docs team approximately every two weeks to align to releases of the CodeQL CLI. The workflow takes an input parameter that specifies the branch to pull the source files from in the codeql repo. If the branch input is omitted, the workflow will default to the `main` branch. +A [workflow](../../.github/workflows/generate-code-scanning-query-lists.yml) is used to trigger the automation of the CodeQL query tables documentation. The workflow is manually triggered by a member of the GitHub Docs team approximately every two weeks to align to releases of the CodeQL CLI. The workflow takes an input parameter that specifies the branch to pull the source files from in the codeql repo. If the branch input is omitted, the workflow will default to the `main` branch. The workflow runs two scripts in parallel: - `npm run generate-code-scanning-query-list` - generates security query tables under `data/reusables/code-scanning/codeql-query-tables/` diff --git a/src/content-render/scripts/reusables-cli/README.md b/src/content-render/scripts/reusables-cli/README.md index 9e492e1ab8b3..eae841f38b02 100644 --- a/src/content-render/scripts/reusables-cli/README.md +++ b/src/content-render/scripts/reusables-cli/README.md @@ -119,7 +119,7 @@ In content/actions/using-workflows/reusing-workflows.md on: Some reusables might not make sense to "reuse" everywhere they could be reused. For instance, at the time of writing there is a reusable that is just the number "30" which shows up in certain files, but doesn't make sense to be replaced with a reusable. -In these cases you can skip these reusables from being checked by the `find potential-uses` command by adding their paths to the array in [src/content-render/scripts/reusables-cli/ignore-reusables.ts](./ignore-unused-reusables.ts) +In these cases you can skip these reusables from being checked by the `find potential-uses` command by adding their paths to the array in [src/content-render/scripts/reusables-cli/ignore-reusables.ts](./ignore-reusables.ts) #### Similarity search diff --git a/src/languages/lib/correct-translation-content.ts b/src/languages/lib/correct-translation-content.ts index c251ab83ac98..d7966b6a3598 100644 --- a/src/languages/lib/correct-translation-content.ts +++ b/src/languages/lib/correct-translation-content.ts @@ -892,10 +892,15 @@ export function correctTranslatedContentStrings( '{%$1 ifversion command-palette $2%}', ) // Run before the конец fallback. Split, not regex, to avoid catastrophic backtracking. + // Only rewrite конец to endraw inside a raw block that isn't already closed by a + // real {% endraw %}; otherwise an unrelated конец later in the document (closing an + // ifversion, say) would be wrongly consumed as this block's closer. if (content.includes('{% конец %}') && content.includes('{% raw %}')) { const parts = content.split('{% raw %}') for (let i = 1; i < parts.length; i++) { - parts[i] = parts[i].replace('{% конец %}', '{% endraw %}') + if (!parts[i].includes('{% endraw %}')) { + parts[i] = parts[i].replace('{% конец %}', '{% endraw %}') + } } content = parts.join('{% raw %}') } diff --git a/src/languages/tests/correct-translation-content.ts b/src/languages/tests/correct-translation-content.ts index 14f0899abc9a..5a49ba4c2cdb 100644 --- a/src/languages/tests/correct-translation-content.ts +++ b/src/languages/tests/correct-translation-content.ts @@ -869,6 +869,18 @@ describe('correctTranslatedContentStrings', () => { expect(fix('{%- конец для %}', 'ru')).toBe('{%- endfor %}') }) + test('does not consume an unrelated конец when an earlier raw block is already closed', () => { + expect( + fix('{% raw %}some content{% endraw %} text {% ifversion x %}more{% конец %}', 'ru'), + ).toBe('{% raw %}some content{% endraw %} text {% ifversion x %}more{% endif %}') + expect( + fix( + '{% raw %}a{% endraw %} mid {% raw %}b{% конец %} tail {% ifversion y %}z{% конец %}', + 'ru', + ), + ).toBe('{% raw %}a{% endraw %} mid {% raw %}b{% endraw %} tail {% ifversion y %}z{% endif %}') + }) + test('fixes заголовки строк → rowheaders', () => { expect(fix('{% заголовки строк %}', 'ru')).toBe('{% rowheaders %}') expect(fix('{%- заголовки строк %}', 'ru')).toBe('{%- rowheaders %}') diff --git a/src/rest/scripts/utils/merge-all-of.ts b/src/rest/scripts/utils/merge-all-of.ts index c027285e46a5..0c3133fddf2e 100644 --- a/src/rest/scripts/utils/merge-all-of.ts +++ b/src/rest/scripts/utils/merge-all-of.ts @@ -79,10 +79,10 @@ function isDeepEqual(a: unknown, b: unknown): boolean { * precedence over later ones. * * Only the cases the GitHub OpenAPI descriptions actually use are merged: - * identical values, `properties`, `required`, and annotations. Anything else - * throws rather than guessing, so a future description that needs real - * conflict resolution fails the build loudly instead of quietly publishing the - * wrong request body parameters. + * identical values, `properties`, `required`, `type`, and annotations. + * Anything else throws rather than guessing, so a future description that + * needs real conflict resolution fails the build loudly instead of quietly + * publishing the wrong request body parameters. */ function mergeInto(target: Schema, source: Schema, path: string): void { for (const [key, value] of Object.entries(source)) { @@ -117,6 +117,22 @@ function mergeInto(target: Schema, source: Schema, path: string): void { continue } + // `type` may be a single type name or an array of allowed type names, and + // different `allOf` members can spell the same constraint differently + // (e.g. `"object"` vs `["object", "null"]`, or the same array in a + // different order). Per JSON Schema, `allOf` members combine as an + // intersection, so the merged type is whichever names both sides allow. + if (key === 'type') { + const existingTypes = Array.isArray(existing) ? existing : [existing] + const valueTypes = Array.isArray(value) ? value : [value] + const intersection = existingTypes.filter((type) => valueTypes.includes(type)) + if (intersection.length === 0) { + throw new Error(`Cannot merge allOf: conflicting "type" keyword at ${path}.`) + } + target[key] = intersection.length === 1 ? intersection[0] : intersection + continue + } + if (ANNOTATION_KEYWORDS.has(key)) continue throw new Error( diff --git a/src/rest/tests/merge-all-of.ts b/src/rest/tests/merge-all-of.ts index 14dd31e8708e..9adc92165564 100644 --- a/src/rest/tests/merge-all-of.ts +++ b/src/rest/tests/merge-all-of.ts @@ -165,6 +165,15 @@ describe('mergeAllOf', () => { ).toEqual({ type: 'object', enum: ['a'] }) }) + test('intersects "type" when allOf members allow different but overlapping types', () => { + expect(mergeAllOf({ allOf: [{ type: 'object' }, { type: ['object', 'null'] }] })).toEqual({ + type: 'object', + }) + expect( + mergeAllOf({ allOf: [{ type: ['object', 'null'] }, { type: ['null', 'object'] }] }), + ).toEqual({ type: ['object', 'null'] }) + }) + test('throws on a conflicting keyword rather than guessing', () => { expect(() => mergeAllOf({ allOf: [{ type: 'string' }, { type: 'number' }] })).toThrow( /conflicting "type" keyword/,