{% data reusables.gated-features.copilot-cli %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' versions: feature: copilot @@ -9,17 +9,31 @@ category: - Learn about Copilot - Learn about Copilot CLI contentType: concepts +redirect_from: + - /copilot/concepts/agents/about-agent-skills --- -> [!NOTE] -> Agent skills work with {% data variables.copilot.copilot_cloud_agent %}, {% data variables.copilot.copilot_code-review_short %}, the {% data variables.copilot.copilot_cli %}, the {% data variables.copilot.github_copilot_app %}, and agent mode in {% data variables.product.prodname_vscode %} and {% data variables.jetbrains.prodname_jetbrains_ides %}. - ## About agent skills Agent skills are folders of instructions, scripts, and resources that {% data variables.product.prodname_copilot_short %} can load when relevant to improve its performance in specialized tasks. The Agent Skills specification is an [open standard](https://github.com/agentskills/agentskills), used by a range of different AI systems. You can create your own skills to teach {% data variables.product.prodname_copilot_short %} to perform tasks in a specific, repeatable way—or use skills shared online, for example in the [`anthropics/skills`](https://github.com/anthropics/skills) repository or {% data variables.product.company_short %}'s community-created [`github/awesome-copilot`](https://github.com/github/awesome-copilot) collection. +For example, a skill for writing release notes can include your team's template, a script for gathering changes, and instructions for grouping them. The agent loads those resources when working on release notes, rather than including the whole workflow in every conversation. + +## Where you can use agent skills + +You can use agent skills with: + +* The {% data variables.copilot.github_copilot_app %}. +* {% data variables.copilot.copilot_cli %}. +* {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %} on {% data variables.product.prodname_dotcom_the_website %}. +* Agent mode in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, and {% data variables.jetbrains.prodname_jetbrains_ides %}. + +IDE support depends on the version you use. See [AUTOTITLE](/copilot/reference/copilot-feature-matrix). + +## Finding and storing skills + You can also use `gh skill` in {% data variables.product.prodname_cli %} to discover and install skills from {% data variables.product.github %} repositories. For more information, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/add-skills#managing-skills-with-github-cli). {% data variables.product.prodname_copilot_short %} supports: @@ -27,6 +41,8 @@ You can also use `gh skill` in {% data variables.product.prodname_cli %} to disc * Project skills, stored in your repository (`.github/skills`, `.claude/skills`, or `.agents/skills`) * Personal skills, stored in your home directory and shared across projects (`~/.copilot/skills` or `~/.agents/skills`) +Supported locations depend on the surface. Use its setup guide to choose a location rather than assuming that a personal skill is available to an agent running in the cloud. + ## Next steps To create or add agent skills, see: diff --git a/content/copilot/concepts/customizations/comparing-customizations.md b/content/copilot/concepts/customizations/comparing-customizations.md new file mode 100644 index 000000000000..52420a32e49f --- /dev/null +++ b/content/copilot/concepts/customizations/comparing-customizations.md @@ -0,0 +1,398 @@ +--- +title: Comparing Copilot customization features +shortTitle: Comparing customizations +intro: 'Choose the right way to give {% data variables.product.prodname_copilot_short %} guidance, specialized expertise, and access to tools.' +versions: + feature: copilot +contentType: concepts +redirect_from: + - /copilot/concepts/agents/copilot-cli/comparing-cli-features +category: + - Learn about Copilot + - Learn about Copilot CLI +--- + +## Introduction + +You can customize {% data variables.product.prodname_copilot_short %} to follow your conventions, carry out repeatable workflows, or connect to systems beyond your codebase. + +This article explains the difference between: + +* **Custom instructions** + + These tell {% data variables.product.prodname_copilot_short %} **how to behave** in general. For example, to ensure code it writes follows your coding standards. [Find out more](#custom-instructions). + +* **Agent skills** + + These tell {% data variables.product.prodname_copilot_short %} **how to handle a specific kind of task**. For example, to follow your team's process when drafting release notes. [Find out more](#agent-skills). + +* **Tools** + + These **provide abilities**. For example, for finding and modifying files, or for interacting with parts of {% data variables.product.github %}. [Find out more](#tools). + +* **MCP servers** + + These **add collections of tools** that allow {% data variables.product.prodname_copilot_short %} to interact with external services. [Find out more](#mcp-servers). + +* **Hooks** + + These let you **run your own logic at specific points in an agent's workflow**. For example, you can run a script before the agent uses a tool. [Find out more](#hooks). + +* **Subagents** + + These **perform delegated work** separately from the main agent. They have their own conversation context, so their intermediate work does not fill the main agent's context window. [Find out more](#subagents). + +* **Custom agents** + + These **define specialized roles**, with instructions and tools for particular tasks. For example, a custom agent might act as a React reviewer, a docs writer, or a test generator. [Find out more](#custom-agents). + +* **Extensions** + + These **add capabilities implemented in code**. For example, a {% data variables.copilot.copilot_cli_short %} extension can add a tool that tracks session activity. [Find out more](#extensions). + +* **Plugins** + + These are **packages** that can deliver preconfigured customizations such as skills, hooks, custom agents, and MCP servers. [Find out more](#plugins). + +Support and configuration differ between surfaces. For a support comparison, see [AUTOTITLE](/copilot/reference/customization-cheat-sheet#ide-and-surface-support). + +## Custom instructions + +Custom instructions are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, {% data variables.copilot.copilot_code-review_short %}, {% data variables.copilot.copilot_chat_short %} on {% data variables.product.prodname_dotcom_the_website %}, and supported IDEs. The types of instructions available depend on where you use them. + +### What are custom instructions? + +Custom instructions are persistent guidance that {% data variables.product.prodname_copilot_short %} uses within a defined scope. For example, repository instructions can describe your project's coding conventions and test commands, while personal instructions can describe your communication preferences. + +Instructions guide the model, but do not guarantee that it will follow every rule. + +### What problem do custom instructions solve? + +Custom instructions help you: + +* Keep {% data variables.product.prodname_copilot_short %} aligned with your coding conventions and preferences. +* Apply team or organization standards consistently. +* Avoid including repetitive reminders in every prompt. + +### When should you use custom instructions? + +Use custom instructions for: + +* Style and quality rules. For example: "Prefer small pull requests, write tests, and avoid changing public APIs without discussion." +* Repository conventions. For example: "Use `pnpm`, keep changelog entries in `CHANGELOG.md`, and run `pnpm test` before committing." +* Communication preferences. For example: "Explain tradeoffs briefly, then provide the recommended choice." + +### When shouldn't you use custom instructions? + +Keep them minimal when: + +* You only want the behavior for one kind of task. Use a skill instead. +* The instructions are so detailed that they distract from the immediate task. Use a skill or a custom agent for specialized guidance. + +### Find out more about custom instructions + +* [AUTOTITLE](/copilot/concepts/prompting-and-context/custom-instructions) +* [AUTOTITLE](/copilot/reference/custom-instructions-support) + +## Agent skills + +Agent skills are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, {% data variables.copilot.copilot_code-review_short %}, and agent mode in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, and {% data variables.jetbrains.prodname_jetbrains_ides %}. + +### What is a skill? + +A skill is a folder containing a `SKILL.md` file with instructions for a specific kind of task. Its name and description help {% data variables.product.prodname_copilot_short %} decide when to load those instructions. + +Skills can also include supporting resources, such as templates and scripts the agent can run. + +### What problem does a skill solve? + +Skills help you: + +* Standardize how {% data variables.product.prodname_copilot_short %} performs tasks in a specific context, such as a code review. +* Provide instructions when they are relevant, without adding them to every interaction. +* Avoid filling the context window with instructions unrelated to the current task. + +### When should you use a skill? + +Use a skill when you want: + +* A repeatable workflow. For example, check that user-facing documentation is updated when frontend code changes. +* A consistent output format. For example, draft release notes using your team's template. +* A workflow you sometimes need, but not always. For example, follow a detailed refactoring process during a migration. + +### When shouldn't you use a skill? + +Choose another customization when: + +* The guidance should apply broadly to your work. Use custom instructions instead. +* You need access to an external system. Use an MCP server to provide the tools, which a skill can then describe how to use. +* You need a reusable specialist with a particular toolset. Consider a custom agent. + +### Find out more about agent skills + +See [AUTOTITLE](/copilot/concepts/customizations/agent-skills). + +## Tools + +Tools are available to agents in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, and supported IDEs. The available tools and permission controls depend on the surface. + +### What is a tool? + +A tool is an ability that {% data variables.product.prodname_copilot_short %} uses to get something done, such as searching files, viewing file contents, editing, or running commands. Some tools are built in, and others can be added through MCP servers or extensions. + +### What problem do tools solve? + +Tools let an agent: + +* Gather context by reading and searching. +* Make changes by editing files. +* Execute commands and validate the results. + +### When are tools used? + +You typically do not call tools directly. {% data variables.product.prodname_copilot_short %} chooses tools to carry out your request, subject to the permissions and controls of the surface you are using. + +You will see tools used when you: + +* Ask an agent to search a repository, update a file, or run tests. +* Ask for work that requires access to an external service through an MCP server. +* Give an agent a task that benefits from delegation to a subagent. + +Before adding an integration, check whether the agent's existing tools already meet your needs. + +## MCP servers + +MCP servers are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, {% data variables.copilot.copilot_code-review_short %}, {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, {% data variables.jetbrains.prodname_jetbrains_ides %}, Xcode, and Eclipse. Configuration and authentication options depend on the surface. + +### What is an MCP server? + +An MCP server is a service that allows AI applications, such as {% data variables.product.prodname_copilot_short %}, to connect to external data sources and tools. + +For example, you could add an MCP server that provides tools for interacting with an online calendar or a support ticketing system. + +### What problem do MCP servers solve? + +MCP servers help when the built-in tools are not enough. They can: + +* Connect {% data variables.product.prodname_copilot_short %} to external systems. +* Add purpose-built tools for working with APIs, databases, or other services. +* Provide access to information outside your repository. + +### When should you use an MCP server? + +Use an MCP server when you need: + +* Information from an external system. For example: "How many support tickets have been opened this month for Product X?" +* Actions in another service. For example: "Add a comment to the support ticket summarizing this fix." + +### When shouldn't you use an MCP server? + +Avoid adding an MCP server when the built-in tools already cover your needs. + +### Find out more about MCP servers + +See [AUTOTITLE](/copilot/concepts/customizations/mcp). + +## Hooks + +Hooks are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, and {% data variables.product.prodname_vscode %}. Supported events and controls depend on the surface. + +### What is a hook? + +A hook runs a shell command you define at a particular point in an agent's workflow. For example, a hook can run before a tool is used or when a session ends. + +Unlike skills and custom instructions, which guide the model through prompts, hooks execute code at defined events. + +### What problem do hooks solve? + +Hooks help when you need more control over agent actions, such as: + +* Checking a tool request before allowing it to run. +* Logging tool use or session activity. +* Running custom validation at a supported event. + +### When should you use hooks? + +Use hooks when you want: + +* Tool checks. For example, check a proposed command against an allowlist before it runs. +* Session automation. For example, record when an agent session starts or ends. +* Custom validation. For example, check whether a tool request would change a protected path. + +Use the event and configuration reference for your surface rather than assuming that a hook works unchanged everywhere. + +### When shouldn't you use hooks? + +Choose another customization when: + +* You just need workflow instructions. Use a skill. +* You want persistent preferences and standards. Use custom instructions. +* You need access to external tools. Use an MCP server. + +### Find out more about hooks + +* [AUTOTITLE](/copilot/concepts/customizations/hooks) +* [AUTOTITLE](/copilot/reference/hooks-reference) + +## Subagents + +Subagents are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.product.prodname_vscode %}, {% data variables.jetbrains.prodname_jetbrains_ides %}, Xcode, and Eclipse. + +### What is a subagent? + +A subagent is an agent that the main agent delegates a specific piece of work to. It works in its own conversation context and reports its results back to the main agent. + +A subagent can use a built-in agent or a custom agent profile. You do not need to define a custom agent for every delegated task. + +### What problem do subagents solve? + +Subagents help an agent: + +* Keep the main conversation focused by handling a subtask in separate context. +* Run independent tasks in parallel where supported. +* Delegate specialist work using a custom agent profile. + +### When are subagents used? + +Subagents are useful for: + +* Codebase exploration. For example, find all endpoints in an API. +* Command execution. For example, run a test suite and summarize failures. +* Reviewing changes. For example, review staged changes while the main agent works on another part of the task. +* Specialist work. For example, delegate a review to a custom documentation agent. + +Selecting a custom agent for your main session is different from delegating work to it as a subagent. + +### Find out more about subagents + +* [AUTOTITLE](/copilot/concepts/agent-capabilities/choosing-and-delegating-agent-work/delegating-and-parallelizing-work-with-agents) +* [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-subagents) + +## Custom agents + +Custom agents are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, {% data variables.jetbrains.prodname_jetbrains_ides %}, Eclipse, and Xcode. Supported profile properties depend on the surface. + +### What is a custom agent? + +A custom agent defines a specialist role, with instructions and available tools for a particular kind of work. You can think of it as a persona that {% data variables.product.prodname_copilot_short %} can adopt, such as a React reviewer or a docs writer. + +You define a custom agent in a Markdown file with YAML frontmatter. Its profile describes its purpose, gives it instructions, and can restrict its available tools. In supported environments, it can also configure MCP servers. + +### What problem do custom agents solve? + +Custom agents help when you need: + +* Specialist guidance applied consistently to particular tasks. +* A different set of tools for different kinds of work. +* A reusable role you can select for a session or use for delegated work. + +Separate context is a benefit of running an agent as a subagent, not a requirement for using a custom agent. + +### When should you use a custom agent? + +Use a custom agent when you want: + +* A specialized reviewer or helper. For example, a React reviewer that checks your team's component patterns. +* A constrained toolset. For example, a reviewer with tools for reading and searching files, but not editing them. +* A consistent approach. For example, a documentation agent that follows your writing and review standards. + +### When shouldn't you use a custom agent? + +Choose a simpler option when: + +* You only need task-specific instructions and resources. A skill may be enough. +* You do not need specialization and the default agent performs the task well. + +### Find out more about custom agents + +* [AUTOTITLE](/copilot/concepts/customizations/custom-agents) +* [AUTOTITLE](/copilot/reference/custom-agents-configuration) + +## Extensions + +Extensions are supported in the {% data variables.copilot.github_copilot_app %} and {% data variables.copilot.copilot_cli_short %}. The examples below describe extensions for {% data variables.copilot.copilot_cli_short %}. + +### What is an extension? + +An extension adds capabilities implemented in code. In {% data variables.copilot.copilot_cli_short %}, an extension is a JavaScript module that runs alongside an interactive session and can add tools, slash commands, and session-aware behavior. + +These are distinct from IDE extensions and the retired {% data variables.product.prodname_github_app %}-based {% data variables.product.prodname_copilot_short %} Extensions integration. + +### What problem do extensions solve? + +Extensions let you build capabilities that need more than instructions or configuration. For example, a {% data variables.copilot.copilot_cli_short %} extension can keep state across tool calls and make it available through a custom tool. + +### When should you use an extension? + +Use an extension when you need: + +* Your own session-aware tools. For example, track tool-call timings across a {% data variables.copilot.copilot_cli_short %} session and expose the totals to the agent. +* A slash command backed by code. For example, add a command that summarizes information collected during a {% data variables.copilot.copilot_cli_short %} session. + +### When shouldn't you use an extension? + +Choose another customization when: + +* Instructions and resources are enough. Use a skill. +* An existing MCP server provides the external tools you need. +* You only need to run a command at a defined event. Use a hook. + +### Find out more about extensions + +See [AUTOTITLE](/copilot/concepts/customizations/extensions). + +## Plugins + +Plugins are supported in the {% data variables.copilot.github_copilot_app %}, {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, and {% data variables.product.prodname_vscode %}. A plugin's supported components depend on the surface. + +### What is a plugin? + +A plugin is an installable package that delivers a bundle of capabilities. For example, it can include skills, custom agents, hooks, and MCP server configurations. + +A plugin packages customizations, but does not replace their individual purposes. + +### What problem do plugins solve? + +Plugins help you: + +* Add related capabilities without configuring each piece separately. +* Distribute a set of customizations to your team or the public. +* Install and update customizations without manually copying files. + +### When should you use a plugin? + +Use a plugin when: + +* You want a team-wide bundle. For example, share incident-response skills, a review agent, and MCP server configuration for internal services. +* You want to install and maintain related capabilities together. + +### When shouldn't you use a plugin? + +Start with individual customizations when: + +* You are experimenting locally and do not need distribution. +* You only need a small workflow. A single skill may be simpler. + +### Find out more about plugins + +See [AUTOTITLE](/copilot/concepts/customizations/plugins). + +## Putting it together: choosing the right option + +Start with the smallest customization that solves your problem. These features can work together: a skill can describe a workflow that uses MCP tools, and a plugin can distribute both. + +| Requirement | Start with | +| --- | --- | +| I want {% data variables.product.prodname_copilot_short %} to follow our repository conventions. | Custom instructions | +| I want a repeatable workflow for a particular kind of task. | Agent skills | +| I want an agent to search my repository, change files, or run tests. | Its existing tools | +| I need tools provided by an external service. | An MCP server | +| I want checks or automation around tool use and session events. | Hooks | +| I want a focused subtask handled separately from the main conversation. | Subagents | +| I want a reusable specialist with a particular approach and toolset. | A custom agent | +| I need to build my own session-aware tools in {% data variables.copilot.copilot_cli_short %}. | An extension | +| I want to install or share related customizations together. | A plugin | + +## Next steps + +For configuration locations and surface support, see [AUTOTITLE](/copilot/reference/customization-cheat-sheet). diff --git a/content/copilot/concepts/customizations/custom-agents.md b/content/copilot/concepts/customizations/custom-agents.md new file mode 100644 index 000000000000..d703aa4e52a8 --- /dev/null +++ b/content/copilot/concepts/customizations/custom-agents.md @@ -0,0 +1,73 @@ +--- +title: Custom agents +shortTitle: Custom agents +intro: 'Give {% data variables.product.prodname_copilot_short %} reusable specialist roles with tailored instructions and tools.' +versions: + feature: copilot +contentType: concepts +redirect_from: + - /copilot/concepts/agents/about-custom-agents + - /copilot/concepts/agents/cloud-agent/about-custom-agents + - /copilot/concepts/agents/copilot-cli/about-custom-agents + - /copilot/concepts/agents/coding-agent/about-custom-agents +category: + - Learn about Copilot + - Learn about Copilot CLI +--- + +{% data variables.copilot.custom_agents_caps_short %} are specialized versions of the {% data variables.product.prodname_copilot_short %} agent that you tailor to particular tasks and workflows. Define a role once instead of repeating its instructions and tool requirements every time you need that expertise. + +For example, you can create a documentation specialist that follows your writing standards, or a reviewer that can read and search files but does not need editing tools. + +## About agent profiles + +An agent profile is a Markdown file with YAML frontmatter. It describes the agent's purpose, gives it instructions, and can restrict its available tools. In supported environments, a profile can also configure MCP servers for that agent. + +Use a custom agent when you need a reusable role with a particular approach and toolset. If you only need task-specific instructions and resources, a skill can be a simpler choice. For a comparison, see [AUTOTITLE](/copilot/concepts/customizations/comparing-customizations). + +Profiles can be shared at repository, organization, and enterprise levels. {% data variables.copilot.copilot_cli_short %} also supports personal profiles. Configuration locations, supported properties, and precedence depend on the environment. See [AUTOTITLE](/copilot/reference/custom-agents-configuration). + +## Where you can use custom agents + +You can use custom agents with: + +* **The {% data variables.copilot.github_copilot_app %}**. +* **{% data variables.copilot.copilot_cli %}**. +* **{% data variables.copilot.copilot_cloud_agent %} on {% data variables.product.prodname_dotcom_the_website %}**, including the agents tab and panel, issue assignment, and pull requests. +* **Supported IDEs**, including {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, {% data variables.jetbrains.prodname_jetbrains_ides %}, Eclipse, and Xcode. + +Custom agents in {% data variables.jetbrains.prodname_jetbrains_ides %} and Xcode are in {% data variables.release-phases.public_preview %}. For IDE-specific version support and release status, see [AUTOTITLE](/copilot/reference/copilot-feature-matrix). + +In an IDE, using a custom agent directly in chat is different from delegating a task to {% data variables.copilot.copilot_cloud_agent %}. A profile's properties can behave differently or be ignored between environments. For {% data variables.product.prodname_vscode_shortname %} profile behavior, see [Custom agents in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/copilot/customization/custom-agents). + +## Built-in agents + +You do not need to define a custom agent for every specialist task. {% data variables.copilot.copilot_cli_short %} includes built-in agents that the main agent can use for common work: + +* `explore` for codebase exploration +* `task` for command execution +* `general-purpose` for work requiring a separate agent context +* `code-review` for reviewing changes +* `research` for research +* `rubber-duck` for a second opinion +* `security-review` for security-focused review + +These are provided by {% data variables.copilot.copilot_cli_short %}, rather than authored as your own profiles. The available tools and behavior differ by agent. For their capabilities and model defaults, see [Built-in agents](/copilot/reference/copilot-cli-reference/cli-command-reference#built-in-agents). + +## Custom agents and subagents + +A custom agent is a **definition of a specialist**. A subagent is **an agent doing delegated work** in a separate context window. The main agent can delegate to a built-in agent or run a specialist using a custom agent profile. + +Separate context lets a subagent focus on its assigned task without adding every intermediate detail to the main conversation. Independent tasks can also run in parallel. These are benefits of delegation, not properties that require you to create a custom profile. + +Selecting a custom agent for a session and delegating a subtask to one are different ways of using a profile. In {% data variables.copilot.copilot_cli_short %}, repository instructions are included for the session agent but are not included for a custom subagent by default. For the opt-in setting and invocation methods, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli). + +For the broader delegation model in the {% data variables.copilot.github_copilot_app %} and {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/concepts/agent-capabilities/choosing-and-delegating-agent-work/delegating-and-parallelizing-work-with-agents). + +## Next steps + +Choose the setup guide for where you work: + +* [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents) +* [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-custom-agents) +* [AUTOTITLE](/copilot/how-tos/github-copilot-app/customize-github-copilot-app) diff --git a/content/copilot/concepts/customizations/extensions.md b/content/copilot/concepts/customizations/extensions.md new file mode 100644 index 000000000000..e0b783f6e289 --- /dev/null +++ b/content/copilot/concepts/customizations/extensions.md @@ -0,0 +1,73 @@ +--- +title: Extensions for GitHub Copilot +shortTitle: Extensions +intro: 'Extend {% data variables.product.prodname_copilot_short %} with capabilities implemented in code.' +versions: + feature: copilot +contentType: concepts +redirect_from: + - /copilot/concepts/agents/copilot-cli/about-cli-extensions +category: + - Learn about Copilot + - Learn about Copilot CLI +--- + +Extensions let you implement capabilities that go beyond prompting the agent. For example, in {% data variables.copilot.copilot_cli %}, an extension can add tools and slash commands backed by code running alongside your session. + +These extensions are distinct from the retired {% data variables.product.prodname_github_app %}-based {% data variables.product.prodname_copilot_short %} Extensions integration. They are also distinct from IDE extensions, such as the {% data variables.product.prodname_copilot_short %} extension you install in an editor. + +## Where you can use extensions + +You can use extensions in: + +* The {% data variables.copilot.github_copilot_app %}. +* {% data variables.copilot.copilot_cli %}. + +For customization options in the {% data variables.copilot.github_copilot_app %}, see [AUTOTITLE](/copilot/how-tos/github-copilot-app/customize-github-copilot-app). + +{% data reusables.copilot.copilot-cli.cli-extensions-experimental %} + +## Choosing an extension scope + +Choose an extension's scope based on who needs it: + +* **Repository extensions** keep project-specific capabilities with the project so you can share them with collaborators. +* **Personal extensions** provide capabilities for your own workflows. +* **Plugin extensions** are supplied as part of an installed plugin, alongside other customizations. + +To create an extension for {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/tutorials/create-an-extension). + +## Extensions in {% data variables.copilot.copilot_cli_short %} + +An extension for {% data variables.copilot.copilot_cli_short %} is a JavaScript module that runs as a separate Node.js process alongside an interactive session. It connects to the session through the extension SDK bundled with {% data variables.copilot.copilot_cli_short %}. + +An extension can add: + +* **Tools** that the agent can call while working on your request. +* **Slash commands** that you invoke yourself. +* Session-aware behavior, such as observing events and keeping state across tool calls. + +Use an extension when a capability needs code that stays active during the session. For example, an extension can track tool-call timings across a session and expose the totals through a tool. + +{% data variables.copilot.copilot_cli_short %} also lets you control whether extensions run and whether the agent can manage them. For the extension modes and their effects, see [Extension modes](/copilot/reference/copilot-cli-reference/cli-command-reference#extension-modes). + +## Choosing between extensions and other customizations + +The distinction is the capability you need, not just where you install it: + +| Need | Start with | +| --- | --- | +| A repeatable workflow expressed as instructions and resources | An agent skill | +| Access to tools exposed by an external service | An MCP server | +| A command at a defined agent lifecycle event | A hook | +| Session-aware tools or slash commands implemented in JavaScript | An extension for {% data variables.copilot.copilot_cli_short %} | +| A distributable bundle of related capabilities | A plugin | + +A plugin can distribute extensions, but the surface determines how those extensions are used. + +> [!WARNING] +> Extensions for {% data variables.copilot.copilot_cli_short %} execute on your computer with your privileges. Only load extension code that you trust, just as you would for any other script you did not write yourself. + +## Next steps + +To compare extensions with the other customization options, see [AUTOTITLE](/copilot/concepts/customizations/comparing-customizations). diff --git a/content/copilot/concepts/agents/hooks.md b/content/copilot/concepts/customizations/hooks.md similarity index 73% rename from content/copilot/concepts/agents/hooks.md rename to content/copilot/concepts/customizations/hooks.md index 672e2d5a4d8e..8218af284fe4 100644 --- a/content/copilot/concepts/agents/hooks.md +++ b/content/copilot/concepts/customizations/hooks.md @@ -1,7 +1,7 @@ --- -title: About hooks for {% data variables.product.prodname_copilot %} +title: Hooks for {% data variables.product.prodname_copilot %} shortTitle: Hooks -intro: 'Extend and customize {% data variables.product.prodname_copilot %} agent behavior by executing custom shell commands at key points during agent execution.' +intro: 'Run your own checks, logging, or other commands at defined points while a {% data variables.product.prodname_copilot_short %} agent works.' versions: feature: copilot contentType: concepts @@ -11,6 +11,7 @@ redirect_from: - /copilot/concepts/agents/coding-agent/about-hooks - /copilot/concepts/agents/cloud-agent/about-hooks - /copilot/concepts/agents/about-hooks + - /copilot/concepts/agents/hooks --- ## What are hooks? @@ -23,16 +24,24 @@ Hooks receive detailed information about agent actions via JSON input, enabling * Use built-in security features like secret scanning to prevent credential leaks. * Implement custom validation rules and audit logging for compliance. -Hooks are available for use with: +Unlike custom instructions, hooks run code rather than asking the model to follow a rule. For example, a hook can run a script that checks a tool request before it executes. -* **{% data variables.copilot.copilot_cloud_agent %}** on {% data variables.product.github %}. -* **{% data variables.copilot.copilot_cli %}** in your terminal. +## Where you can use hooks -You define hooks in JSON files, stored in your repository at `.github/hooks/*.json`. These apply whenever {% data variables.product.prodname_copilot_short %} agents are used in the repository. {% data variables.copilot.copilot_cli_short %} also supports personal hooks that you store in your home directory at `~/.copilot/hooks/*.json`. These apply whenever you use {% data variables.copilot.copilot_cli_short %}. +Hooks are available in: + +* **The {% data variables.copilot.github_copilot_app %}**, which supports repository hooks and hooks supplied by plugins. See [AUTOTITLE](/copilot/how-tos/github-copilot-app/customize-github-copilot-app). +* **{% data variables.copilot.copilot_cli %}**, where commands run in its execution environment. +* **{% data variables.copilot.copilot_cloud_agent %}**, where commands run in the agent's cloud environment. Only a subset of events is supported. +* **{% data variables.product.prodname_vscode %}**, where the hooks experience is in {% data variables.release-phases.public_preview %}. Supported events and configuration depend on the agent running the session. See [Agent hooks in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/agent-customization/hooks). + +The configuration and examples below describe hooks for {% data variables.copilot.copilot_cli_short %} and {% data variables.copilot.copilot_cloud_agent %}. Do not assume that the same events, input, or output work unchanged across surfaces. + +For {% data variables.copilot.copilot_cli_short %} and {% data variables.copilot.copilot_cloud_agent %}, you can define repository hooks in `.github/hooks/*.json`. {% data variables.copilot.copilot_cli_short %} also supports personal hooks in `~/.copilot/hooks/*.json`. For execution environments, additional locations, and event support, see [AUTOTITLE](/copilot/reference/hooks-reference). ## Types of hooks -The following types of hooks are available: +These are examples of {% data variables.copilot.copilot_cli_short %} hook events. {% data variables.copilot.copilot_cloud_agent %} supports a subset: * **sessionStart**: Executed when a new agent session begins or when resuming an existing session. Can be used to initialize environments, log session starts for auditing, validate project state, and set up temporary resources. * **sessionEnd**: Executed when the agent session completes or is terminated. Can be used to cleanup temporary resources, generate and archive session reports and logs, or send notifications about session completion. @@ -43,7 +52,7 @@ The following types of hooks are available: * **subagentStop**: Executed when a subagent completes, before returning results to the parent agent. * **errorOccurred**: Executed when an error occurs during agent execution. Can be used to log errors for debugging, send notifications, track error patterns, and generate reports. -To see a complete reference of hook types with example use cases, best practices, and advanced patterns, see [AUTOTITLE](/copilot/reference/hooks-reference). +The hooks reference lists the full set of events and their availability in {% data variables.copilot.copilot_cloud_agent %}. ## Hook configuration format @@ -80,7 +89,7 @@ The hook object can contain the following keys: ## Example hook configuration file -This is an example configuration file that lives in `~/.github/hooks/project-hooks.json` within a repository. +This is an example configuration file that lives in `.github/hooks/project-hooks.json` within a repository. ```json copy { diff --git a/content/copilot/concepts/customizations/index.md b/content/copilot/concepts/customizations/index.md new file mode 100644 index 000000000000..b45bf9dd7a01 --- /dev/null +++ b/content/copilot/concepts/customizations/index.md @@ -0,0 +1,17 @@ +--- +title: Customizations for GitHub Copilot +shortTitle: Customizations +intro: Extend {% data variables.copilot.copilot_cli_short %} for your own workflows, and for organizations, standardize how {% data variables.copilot.copilot_cli_short %} is customized across teams. +versions: + feature: copilot +children: + - /comparing-customizations + - /agent-skills + - /custom-agents + - /mcp + - /hooks + - /extensions + - /plugins + - /lsp-servers +contentType: concepts +--- diff --git a/content/copilot/concepts/agents/copilot-cli/lsp-servers.md b/content/copilot/concepts/customizations/lsp-servers.md similarity index 86% rename from content/copilot/concepts/agents/copilot-cli/lsp-servers.md rename to content/copilot/concepts/customizations/lsp-servers.md index 3628b4247964..cf622465f5ef 100644 --- a/content/copilot/concepts/agents/copilot-cli/lsp-servers.md +++ b/content/copilot/concepts/customizations/lsp-servers.md @@ -5,6 +5,8 @@ allowTitleToDifferFromFilename: true intro: 'LSP servers give {% data variables.copilot.copilot_cli_short %} precise code intelligence, enabling it to navigate definitions, find references, and rename symbols accurately across your project.' versions: feature: copilot +redirect_from: + - /copilot/concepts/agents/copilot-cli/lsp-servers contentType: concepts docsTeamMetrics: - copilot-cli @@ -23,7 +25,7 @@ The Language Server Protocol (LSP) is an open standard used for communication be * **Accuracy**: Results come from the language's own compiler/analyzer, providing an understanding of the structure of your code. This improves {% data variables.product.prodname_copilot_short %}'s precision when it works with your code. For example, when {% data variables.product.prodname_copilot_short %} can use "go to definition" it will find the actual definition, not a text match that looks similar. * **Token efficiency**: Operations like "list all symbols" or "find references" return compact structured results instead of requiring the agent to read entire files into the conversation. -* **Safe refactoring**: When you rename a symbol, the LSP server reliably updates every reference across the project. +* **Refactoring**: The language server can find and update references when renaming a symbol, rather than relying on text replacement. * **Speed**: Language servers index your project in the background, allowing near-instant responses. ## What LSP servers allow {% data variables.copilot.copilot_cli_short %} to do @@ -50,7 +52,7 @@ The following language server operations are supported: For {% data variables.copilot.copilot_cli_short %} to be able to use an LSP server, you must first install the server software on your local machine and then configure it in one of the configuration files that {% data variables.copilot.copilot_cli_short %} reads on startup. See [AUTOTITLE](/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers). -An LSP server may also be added as part of a CLI plugin that you choose to install. A plugin might include an LSP server if, for example, it's designed to work with an uncommon programming language or a framework-specific file type. LSP servers included as part of a plugin are automatically available when you install the plugin—no additional configuration is needed. If you uninstall the plugin, the LSP server is removed. For more information, see [AUTOTITLE](/copilot/concepts/agents/about-plugins). +An LSP server may also be added as part of a {% data variables.copilot.copilot_cli_short %} plugin that you choose to install. A plugin might include an LSP server if, for example, it's designed to work with an uncommon programming language or a framework-specific file type. LSP servers included as part of a plugin are automatically available when you install the plugin—no additional configuration is needed. If you uninstall the plugin, the LSP server is removed. For more information, see [AUTOTITLE](/copilot/concepts/customizations/plugins). ## How LSP servers are loaded diff --git a/content/copilot/concepts/context/mcp.md b/content/copilot/concepts/customizations/mcp.md similarity index 55% rename from content/copilot/concepts/context/mcp.md rename to content/copilot/concepts/customizations/mcp.md index c412343d3582..78c566ba9373 100644 --- a/content/copilot/concepts/context/mcp.md +++ b/content/copilot/concepts/customizations/mcp.md @@ -1,12 +1,16 @@ --- -title: About Model Context Protocol (MCP) +title: Model Context Protocol (MCP) allowTitleToDifferFromFilename: true shortTitle: MCP -intro: Model Context Protocol (MCP) is a protocol that allows you to extend the capabilities of {% data variables.product.prodname_copilot %} by integrating it with other systems. +intro: 'Connect {% data variables.product.prodname_copilot_short %} to external tools and data through Model Context Protocol (MCP) servers.' versions: feature: copilot contentType: concepts redirect_from: + - /copilot/concepts/context/mcp + - /copilot/concepts/agents/cloud-agent/mcp-and-cloud-agent + - /copilot/concepts/agents/coding-agent/mcp-and-coding-agent + - /copilot/concepts/coding-agent/mcp-and-coding-agent - /copilot/concepts/about-mcp - /copilot/concepts/extensions/agents - /copilot/concepts/extensions/build-extensions @@ -30,6 +34,7 @@ redirect_from: - /copilot/using-github-copilot/using-extensions-to-integrate-external-tools-with-copilot-chat category: - Learn about Copilot + - Integrate Copilot with your tools --- ## Overview of Model Context Protocol (MCP) @@ -38,25 +43,67 @@ category: You can use MCP to extend the capabilities of {% data variables.product.prodname_copilot %} by integrating it with a wide range of existing tools and services. MCP works across all major {% data variables.product.prodname_copilot_short %} surfaces—whether you're working in an IDE, using {% data variables.copilot.copilot_cli %}, working in the {% data variables.copilot.github_copilot_app %}, or delegating tasks to an agent on {% data variables.product.prodname_dotcom_the_website %}. You can also use MCP to create new tools and services that work with {% data variables.product.prodname_copilot_short %}, allowing you to customize and enhance your experience. -For more information on MCP, see [the official MCP documentation](https://modelcontextprotocol.io/introduction). For a curated list of MCP servers from partners and the community, see the [{% data variables.product.github %} MCP Registry](https://github.com/mcp). +For example, you can connect an issue tracker so {% data variables.product.prodname_copilot_short %} can look up a bug while working on a fix, without asking you to copy the issue into chat. -To learn how to configure and use MCP servers, see: +For more information on MCP, see [the official MCP documentation](https://modelcontextprotocol.io/introduction). For a curated list of MCP servers from partners and the community, see the [{% data variables.product.github %} MCP Registry](https://github.com/mcp). -* [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp) for {% data variables.copilot.copilot_chat_short %} in your IDE -* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) for {% data variables.copilot.copilot_cli_short %} -* [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers) for repository MCP configuration on {% data variables.product.prodname_dotcom_the_website %} -* [AUTOTITLE](/copilot/how-tos/github-copilot-app/customize-github-copilot-app) for information on MCP server support in the {% data variables.copilot.github_copilot_app %} {% data reusables.copilot.mcp.mcp-policy %} -## Availability +MCP complements the context you provide through prompts, files, and instructions. It adds connections to tools and data, rather than replacing guidance about how the agent should work. For guidance about prompting and managing context, see [AUTOTITLE](/copilot/concepts/prompting-and-context). -MCP is supported across the following clients: +## Where you can use MCP -* **IDEs**: There is broad support for local MCP servers in clients such as {% data variables.product.prodname_vscode %}, JetBrains IDEs, Xcode, and others. Support for remote MCP servers is growing, with editors like {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, JetBrains IDEs, Xcode, Eclipse, Cursor, and Windsurf providing this functionality with OAuth or PAT. To find out if your preferred editor supports remote MCP servers, check the documentation for your specific editor. +MCP setup depends on where you use {% data variables.product.prodname_copilot_short %}: + +* **The {% data variables.copilot.github_copilot_app %}**: You can use MCP servers configured for your repository or in your local {% data variables.product.prodname_copilot_short %} configuration. You can also discover and install additional MCP servers from the **Customize** tab. * **{% data variables.copilot.copilot_cli_short %}**: {% data variables.copilot.copilot_cli %} supports both local and remote MCP servers. The {% data variables.product.github %} MCP server is built in and available without additional configuration. -* **The {% data variables.copilot.github_copilot_app %}**: The {% data variables.copilot.github_copilot_app %} supports MCP servers configured in your repository or {% data variables.copilot.copilot_cli_short %} and lets you add additional MCP servers in app settings. -* **Chat on {% data variables.product.prodname_dotcom_the_website %}**: Chat is preconfigured with tools for tasks such as creating branches, updating files, and semantic code search. See [AUTOTITLE](/copilot/concepts/copilot-surfaces/copilot-on-github). * **{% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %}**: {% data variables.product.prodname_dotcom_the_website %} supports MCP servers configured at the repository level. The configuration applies to both {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %}. The {% data variables.product.github %} MCP server and Playwright MCP server are configured by default. +* **IDEs**: MCP servers are supported in {% data variables.product.prodname_vscode %}, {% data variables.product.prodname_vs %}, {% data variables.jetbrains.prodname_jetbrains_ides %}, Xcode, and Eclipse. Connection and authentication options depend on the IDE. See [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp). + +Chat on {% data variables.product.prodname_dotcom_the_website %} has preconfigured tools, such as tools for creating branches and searching code. This is separate from the repository MCP settings for {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %}. See [AUTOTITLE](/copilot/concepts/copilot-surfaces/copilot-on-github). + +## MCP for {% data variables.copilot.copilot_cloud_agent %} + +The following sections describe MCP defaults and configuration for {% data variables.copilot.copilot_cloud_agent %}. Repository-level MCP settings also apply to {% data variables.copilot.copilot_code-review_short %}, as noted below. For other surfaces, use the setup guides in [Next steps](#next-steps). + +### Default MCP servers + +{% data variables.copilot.copilot_cloud_agent %} starts with two MCP servers configured: + +* **{% data variables.product.github %}** provides access to repository data such as issues and pull requests. By default, it uses a specially scoped token with read-only access to the current repository. Access outside that repository requires explicitly configuring credentials with broader access. +* **Playwright** provides tools to read, interact with, and take screenshots of web pages. By default, it can only access web resources in the agent's own environment through `localhost` or `127.0.0.1`. + +These defaults are specific to the cloud environment. For example, {% data variables.copilot.copilot_cli_short %} includes the {% data variables.product.github %} MCP server without additional configuration, but you configure other servers separately. + +### Repository-level configuration + +Repository administrators can configure MCP servers in repository settings on {% data variables.product.prodname_dotcom_the_website %}. These settings are shared by {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %}. You can disable MCP tool use for code review separately. + +This repository setting is distinct from project MCP configuration files used by {% data variables.copilot.copilot_cli_short %}. Use the setup guide for your surface rather than assuming that the same configuration location applies everywhere. + +> [!WARNING] +> {% data variables.copilot.copilot_cloud_agent %} uses configured MCP tools autonomously and does not ask for approval before calling them. Review each server and allow only the tools and access needed for your tasks. + +{% data reusables.copilot.mcp.repo-mcp-limitations %} + +{% data variables.copilot.copilot_code-review_short %} additionally requires tools to declare `annotations.readOnlyHint: true`. Tools with this annotation missing or set to `false` are excluded. + +For configuration, authentication, and validation procedures, see [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers). + +### MCP servers for custom agents + +For {% data variables.copilot.copilot_cloud_agent %}, an agent profile can define MCP servers for that custom agent, rather than making them available to every agent working in the repository. The `mcp-servers` profile property is not used by custom agents running directly in IDEs. + +For {% data variables.copilot.copilot_cloud_agent %}, default server configurations are processed first, then custom agent configurations, then repository settings. Later configurations can override earlier settings. This order does not describe project-file precedence in {% data variables.copilot.copilot_cli_short %}. + +For the profile format, supported properties, and processing rules, see [AUTOTITLE](/copilot/reference/custom-agents-configuration). + +## Best practices + +* Review third-party servers before enabling them. Check their tools, authentication requirements, and data access against your organization's requirements. +* Enable only the tools a task needs. In repository settings, use the `tools` field to allowlist specific tools, preferably read-only tools, rather than enabling every tool. +* Keep credentials scoped to the required resources. Do not broaden the default token's access for {% data variables.copilot.copilot_cloud_agent %} unless the task needs it. +* Validate configuration before relying on it. Confirm which servers and tools are available in your agent session. For setup instructions for your environment, see [Next steps](#next-steps). ## About the {% data variables.product.github %} MCP server @@ -69,7 +116,7 @@ The {% data variables.product.github %} MCP server is a Model Context Protocol ( * Enable cloud-based workflows that work from any device, without local setup. * Invoke {% data variables.product.github %} tools, such as {% data variables.copilot.copilot_cloud_agent %} (requires {% data variables.product.prodname_copilot %} subscription) and {% data variables.product.prodname_code_scanning %} (requires {% data variables.product.prodname_GHAS %} subscription), to assist with code generation and security analysis. -To learn how to set up and use the {% data variables.product.github %} MCP server, see [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/copilot-for-common-tasks/use-the-github-mcp-server). +To learn how to use the {% data variables.product.github %} MCP server, see [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/copilot-for-common-tasks/use-the-github-mcp-server). To find out whether your editor supports the {% data variables.product.github %} MCP server, and which connection and authentication methods are available, see [Support by host application](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/README.md#support-by-host-application) in the `github/github-mcp-server` repository. @@ -98,22 +145,21 @@ For all public repositories, and private repositories covered by {% data variabl ## About the {% data variables.product.github %} MCP Registry -The {% data variables.product.github %} MCP Registry is a curated list of MCP servers from partners and the community. You can use the registry to discover new MCP servers and find ones that meet your specific needs. See [the {% data variables.product.github %} MCP Registry](https://github.com/mcp). +The {% data variables.product.github %} MCP Registry is a curated list of MCP servers from partners and the community. You can use the registry to discover new MCP servers and find ones that meet your specific needs. ->[!NOTE] +> [!NOTE] > The {% data variables.product.github %} MCP Registry is currently in {% data variables.release-phases.public_preview %} and subject to change. ## Agent finder Agent finder is a discovery service that helps {% data variables.product.prodname_copilot %} find the right capabilities—such as MCP servers, tools, agents, and skills—for a task at runtime, instead of requiring every capability to be configured in advance. Like an MCP registry, it searches a catalog of capabilities and returns ranked matches that {% data variables.product.prodname_copilot %} can use on demand. Agent finder implements the open Agentic Resource Discovery (ARD) specification. -To use agent finder, download the [agent finder skill](https://github.com/ards-project/connectors/blob/main/skills/github-copilot/SKILL.md) and add it to your `~/.copilot/skills` directory. For more information about agent skills, see [AUTOTITLE](/copilot/concepts/agents/about-agent-skills). To browse the catalog, see [GitHub Agent Finder](https://github.com/agentfinder). +For {% data variables.copilot.copilot_cli_short %} setup, see [Using agent finder](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers#using-agent-finder). The {% data variables.copilot.github_copilot_app %} provides an `af` built-in skill. See [AUTOTITLE](/copilot/reference/github-copilot-app-reference/built-in-skills). To browse the catalog, see [GitHub Agent Finder](https://github.com/agentfinder). ## Next steps -* [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp)—Add MCP servers to {% data variables.copilot.copilot_chat_short %} in your IDE +* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)—Add MCP servers to {% data variables.copilot.copilot_cli_short %} +* [AUTOTITLE](/copilot/how-tos/github-copilot-app/customize-github-copilot-app)—Manage MCP servers in the {% data variables.copilot.github_copilot_app %} * [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers)—Configure repository MCP servers for {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_code-review_short %} +* [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp)—Add MCP servers to {% data variables.copilot.copilot_chat_short %} in your IDE * [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/set-up-the-github-mcp-server)—Set up the {% data variables.product.github %} MCP server -* [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/copilot-for-common-tasks/use-the-github-mcp-server)—Use the {% data variables.product.github %} MCP server -* [AUTOTITLE](/copilot/tutorials/enhance-agent-mode-with-mcp) -* [AUTOTITLE](/copilot/reference/customization-cheat-sheet) diff --git a/content/copilot/concepts/agents/about-plugins.md b/content/copilot/concepts/customizations/plugins.md similarity index 77% rename from content/copilot/concepts/agents/about-plugins.md rename to content/copilot/concepts/customizations/plugins.md index 188c7fde9063..868565c27b29 100644 --- a/content/copilot/concepts/agents/about-plugins.md +++ b/content/copilot/concepts/customizations/plugins.md @@ -1,35 +1,45 @@ --- -title: About {% data variables.product.prodname_copilot %} plugins +title: Plugins for {% data variables.product.prodname_copilot %} shortTitle: Plugins allowTitleToDifferFromFilename: true -intro: 'Plugins are installable packages that extend {% data variables.product.prodname_copilot_short %} with reusable agents, skills, hooks, and integrations.' +intro: Plugins are installable packages that extend {% data variables.product.prodname_copilot_short %} with reusable agents, skills, hooks, and integrations. product: '{% data reusables.gated-features.copilot-cli %}
{% data reusables.gated-features.copilot-cloud-agent %}
{% data reusables.gated-features.github-app %}
Sign up for {% data variables.product.prodname_copilot_short %} {% octicon "link-external" height:16 %}' versions: feature: copilot contentType: concepts category: - - Learn about Copilot # Copilot discovery page - - Learn about Copilot CLI # Copilot CLI bespoke page + - Learn about Copilot + - Learn about Copilot CLI docsTeamMetrics: - copilot-cli redirect_from: - /copilot/concepts/agents/copilot-cli/about-cli-plugins + - /copilot/concepts/agents/about-plugins --- -Plugins provide a way to distribute custom {% data variables.product.prodname_copilot_short %} functionality. You can use a plugin to add a preconfigured set of capabilities to {% data variables.product.prodname_copilot_short %}, including {% data variables.copilot.copilot_cli_short %}, {% data variables.copilot.copilot_cloud_agent %}, and the {% data variables.copilot.github_copilot_app %}. +Plugins let you install related customizations together instead of setting up each one separately. For example, a testing plugin could combine a skill for running tests, a review agent, and an MCP server for a test-reporting service. -## What is a plugin? +## Where you can use plugins -* A distributable package that extends {% data variables.product.prodname_copilot_short %}'s functionality. -* A bundle of components in a single installable unit. +You can use plugins in: + +* The {% data variables.copilot.github_copilot_app %}. +* {% data variables.copilot.copilot_cli %}. +* {% data variables.copilot.copilot_cloud_agent %}. +* {% data variables.product.prodname_vscode %}. For supported components and installation, see [Agent plugins in {% data variables.product.prodname_vscode_shortname %}](https://code.visualstudio.com/docs/agent-customization/agent-plugins). + +A plugin can contain components that only work in a particular surface. Check that the plugin supports the surface you use. For example, the LSP server configuration described in this category is for {% data variables.copilot.copilot_cli_short %}. + +The component paths and directory examples below describe plugin formats for {% data variables.copilot.copilot_cli_short %}. Other surfaces can support different components. ## What plugins contain A plugin can contain some or all of the following components. The locations of these components depend on the plugin format: * **Custom agents** — Specialized AI assistants (`*.agent.md` files in `agents/`) -* **Skills** — Discrete callable capabilities (skills subdirectories in `skills/`, containing a `SKILL.md` file) +* **Skills** — Task-specific instructions, scripts, and resources (skills subdirectories in `skills/`, containing a `SKILL.md` file) * **Hooks** — Event handlers that intercept agent behavior (a `hooks.json` file in the plugin root, or in `hooks/`) +* **Extensions** — Code that adds capabilities such as tools and slash commands in supported surfaces * **MCP server configurations** — Model Context Protocol integrations * **LSP server configurations** — Language Server Protocol integrations (an `lsp.json` file in the plugin root, or in `.github/`) @@ -120,9 +130,10 @@ Examples of marketplaces include: How you install a plugin depends on which client you're using: -* In {% data variables.copilot.copilot_cli_short %}, you can install plugins imperatively using the `copilot plugin install` command or the `/plugin install` slash command, or declaratively by adding the plugin to the `enabledPlugins` field of either a user-level `~/.copilot/settings.json` file or a repository-level `.github/copilot/settings.json` file. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing). -* In {% data variables.copilot.copilot_cloud_agent %}, you install plugins declaratively by adding them to the `enabledPlugins` field of the repository's `.github/copilot/settings.json` file. To install plugins from a marketplace that isn't registered by default, you can also add the marketplace to the `extraKnownMarketplaces` field in the same file. +* In {% data variables.copilot.copilot_cli_short %}, you can install plugins using the `copilot plugin install` command or the `/plugin install` slash command, or by adding the plugin to the `enabledPlugins` field of either a user-level `~/.copilot/settings.json` file or a repository-level `.github/copilot/settings.json` file. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/plugins-finding-installing). +* In {% data variables.copilot.copilot_cloud_agent %}, you install plugins by adding them to the `enabledPlugins` field of the repository's `.github/copilot/settings.json` file. To install plugins from a marketplace that isn't registered by default, you can also add the marketplace to the `extraKnownMarketplaces` field in the same file. * In the {% data variables.copilot.github_copilot_app %}, click **Customize**, then click **Plugins** to browse marketplaces and install plugins. +* In {% data variables.product.prodname_vscode %}, use the plugin marketplace commands described in the {% data variables.product.prodname_vscode_shortname %} documentation linked above. Enterprise administrators can define plugin standards that apply to users on the enterprise's {% data variables.product.prodname_copilot_short %} plan, including specifying additional marketplaces and plugins that are automatically installed. See [AUTOTITLE](/copilot/concepts/enterprise/plugin-standards). @@ -147,6 +158,7 @@ Any functionality that you could add with a plugin, you could also add by config ## Further reading +* [AUTOTITLE](/copilot/concepts/customizations/extensions) * [AUTOTITLE](/copilot/concepts/agents/about-agent-skills) * [AUTOTITLE](/copilot/concepts/agents/hooks) -* [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents) +* [AUTOTITLE](/copilot/concepts/customizations/custom-agents) diff --git a/content/copilot/concepts/enterprise/agent-management.md b/content/copilot/concepts/enterprise/agent-management.md index 002e2b050e0f..cb61e0c32990 100644 --- a/content/copilot/concepts/enterprise/agent-management.md +++ b/content/copilot/concepts/enterprise/agent-management.md @@ -37,7 +37,7 @@ You can manage your enterprise-level {% data variables.copilot.custom_agents_sho * From the AI Controls view * Using the REST API. See [AUTOTITLE](/rest/copilot/copilot-custom-agents). -For more detailed information on {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). +For more detailed information on {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/concepts/customizations/custom-agents). ## Agent sessions diff --git a/content/copilot/concepts/enterprise/default-availability.md b/content/copilot/concepts/enterprise/default-availability.md index 64e31b3fcaf7..328889d8a21e 100644 --- a/content/copilot/concepts/enterprise/default-availability.md +++ b/content/copilot/concepts/enterprise/default-availability.md @@ -91,7 +91,7 @@ Model status | Description **Enabled** or **Disabled** | Explicitly configured. **Does not follow** the default availability policy. **Delegate to default policy** | Has not been configured. **Follows** the default availability policy. **Unconfigured** | Has not been configured. **Does not follow** the default availability policy. For example, a model in preview. -**Delegate to organizations** or **Delegate to Enterprise Teams/Apps** | (Depends on whether you have enabled enterprise teams mode.) Explicitly configured. **Does not follow** the default availability policy at the enterprise level. However, if delegated to organizations, **will follow** the organization-level default availability policy _for each organization that does not explicitly configure the model_. +**Delegate to organizations** or **Delegate to Enterprise Teams/Apps** | (Depends on whether you have enabled enterprise teams mode.) Explicitly configured. **Does not follow** the default availability policy at the enterprise level. However, if delegated to organizations, **will follow** the organization-level default availability policy _for each organization that does not explicitly configure the model_. ## How do I prevent default enablement? diff --git a/content/copilot/concepts/index.md b/content/copilot/concepts/index.md index 8ed9abdb3540..96c3672eb47e 100644 --- a/content/copilot/concepts/index.md +++ b/content/copilot/concepts/index.md @@ -6,10 +6,9 @@ versions: feature: copilot children: - /copilot-surfaces - - /agents - /agent-capabilities - /prompting-and-context - - /context + - /customizations - /models - /billing-and-usage - /security-governance-and-network-settings diff --git a/content/copilot/concepts/prompting-and-context/index.md b/content/copilot/concepts/prompting-and-context/index.md index 51af469c1b29..7f0478de63ae 100644 --- a/content/copilot/concepts/prompting-and-context/index.md +++ b/content/copilot/concepts/prompting-and-context/index.md @@ -7,6 +7,7 @@ versions: feature: copilot redirect_from: - /copilot/concepts/prompting + - /copilot/concepts/context children: - /prompt-engineering - /context-management diff --git a/content/copilot/get-started/where-to-use-github-copilot.md b/content/copilot/get-started/where-to-use-github-copilot.md index 3a141937fc8d..a50c9a0ba64c 100644 --- a/content/copilot/get-started/where-to-use-github-copilot.md +++ b/content/copilot/get-started/where-to-use-github-copilot.md @@ -74,7 +74,7 @@ Your choices hold across the workflow, including: * **Which model**: Different models suit different kinds of work, and you can switch models for chat and agents. See [AUTOTITLE](/copilot/how-tos/use-ai-models/change-the-chat-model). * **Which agents**: {% data variables.product.prodname_copilot_short %} agents and agents from other providers work in the same repositories, open pull requests, and go through review. {% data variables.product.prodname_copilot_short %} applies the same security protections, mitigations, and limitations to third-party agents as it does to {% data variables.copilot.copilot_cloud_agent %}. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-cloud-agent) and [AUTOTITLE](/copilot/concepts/agent-capabilities/about-agents/about-third-party-coding-agents). -* **What {% data variables.product.prodname_copilot_short %} can see**: Custom instructions, agent skills, and MCP servers connect {% data variables.product.prodname_copilot_short %} to your conventions and to the tools your team uses. See [AUTOTITLE](/copilot/concepts/context/mcp). +* **What {% data variables.product.prodname_copilot_short %} can see**: Custom instructions, agent skills, and MCP servers connect {% data variables.product.prodname_copilot_short %} to your conventions and to the tools your team uses. See [AUTOTITLE](/copilot/concepts/customizations/mcp). * **What {% data variables.product.prodname_copilot_short %} remembers**: For supported features, {% data variables.copilot.copilot_memory %} can reuse repository facts and your preferences in later work. See [AUTOTITLE](/copilot/concepts/prompting-and-context/copilot-memory). For organizations, administrator policies apply across most surfaces developers use. See [AUTOTITLE](/copilot/how-tos/administer-copilot). diff --git a/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent.md b/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent.md index d768c39b671e..df71a0d48b61 100644 --- a/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent.md +++ b/content/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/enable-copilot-cloud-agent.md @@ -43,7 +43,7 @@ You may want to run a trial before enabling {% data variables.copilot.copilot_cl ## Enabling MCP servers -{% data variables.copilot.copilot_cloud_agent %} automatically has access to a small number of default MCP servers. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/mcp-and-cloud-agent#default-mcp-servers). +{% data variables.copilot.copilot_cloud_agent %} automatically has access to a small number of default MCP servers. See [AUTOTITLE](/copilot/concepts/customizations/mcp#default-mcp-servers). You can enable third-party MCP servers to allow developers to integrate {% data variables.copilot.copilot_cloud_agent %} with other services in your DevOps toolchain, such as error-tracking platforms or logging systems. diff --git a/content/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents.md b/content/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents.md index 7a1e831bed7d..60ca335cbf03 100644 --- a/content/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents.md +++ b/content/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents.md @@ -15,7 +15,7 @@ category: ## Prerequisites -You should understand what {% data variables.copilot.copilot_custom_agents %} are and how they work. See [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). +You should understand what {% data variables.copilot.copilot_custom_agents %} are and how they work. See [AUTOTITLE](/copilot/concepts/customizations/custom-agents). > [!NOTE] > If your organization is part of an enterprise, enterprise owners can configure a ruleset that restricts {% data variables.copilot.custom_agents_short %}. Contact your enterprise owners to check whether you can create and manage organization-level {% data variables.copilot.custom_agents_short %}. diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md index d5a0d98ebc36..36152901cf52 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers.md @@ -13,7 +13,7 @@ docsTeamMetrics: - copilot-cli --- -The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). You can connect MCP servers to {% data variables.copilot.copilot_cli %} to give {% data variables.product.prodname_copilot_short %} access to external tools, data sources, and services. For an overview of MCP, see [AUTOTITLE](/copilot/concepts/context/mcp). +The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). You can connect MCP servers to {% data variables.copilot.copilot_cli %} to give {% data variables.product.prodname_copilot_short %} access to external tools, data sources, and services. For an overview of MCP, see [AUTOTITLE](/copilot/concepts/customizations/mcp). ## Adding an MCP server @@ -205,6 +205,13 @@ If your organization has configured a custom MCP registry URL, `/mcp search` con 1. Press Ctrl+S to save. The server is added to your `mcp-config.json` and started immediately. +## Using agent finder + +Agent finder searches a catalog of capabilities, including MCP servers, tools, agents, and skills. To make it available in the CLI: + +1. Download the [agent finder skill](https://github.com/ards-project/connectors/blob/main/skills/github-copilot/SKILL.md). +1. Add the skill to your `~/.copilot/skills` directory. For skill directory structure and installation guidance, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-skills). + ## Managing MCP servers You can manage your configured MCP servers using the `/mcp` commands in interactive mode or the `copilot mcp` subcommands from the terminal. @@ -271,6 +278,6 @@ Once you have added an MCP server, {% data variables.product.prodname_copilot_sh ## Further reading -* [AUTOTITLE](/copilot/concepts/context/mcp) +* [AUTOTITLE](/copilot/concepts/customizations/mcp) * [AUTOTITLE](/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp) * [AUTOTITLE](/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers) diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/add-skills.md b/content/copilot/how-tos/copilot-cli/customize-copilot/add-skills.md index 8027a419c12b..2ec42d4875c3 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/add-skills.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/add-skills.md @@ -57,4 +57,4 @@ The `/skills` commands above run inside an interactive session. The same list, a {% data reusables.copilot.skills-compared %} -To learn more about how skills differ from other customization features, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/comparing-cli-features). +To learn more about how skills differ from other customization features, see [AUTOTITLE](/copilot/concepts/customizations/comparing-customizations). diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli.md b/content/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli.md index 2b2deb263c64..6d2e3dececd9 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli.md @@ -20,9 +20,9 @@ docsTeamMetrics: When you prompt {% data variables.product.prodname_copilot_short %} to carry out a task it may choose to use one of your {% data variables.copilot.custom_agents_short %}, if {% data variables.product.prodname_copilot_short %} determines that the agent's expertise is a good fit for the task. -Work performed by a {% data variables.copilot.copilot_custom_agent_short %} is carried out using a subagent, which is a temporary agent spun up to complete the task. The subagent has its own context window, which can be populated by information that is not relevant to the main agent. In this way, especially for larger tasks, parts of the work can be offloaded to {% data variables.copilot.custom_agents_short %}, without cluttering the main agent's context window. The main agent can then focus on higher-level planning and coordination. +When the main agent delegates work to a {% data variables.copilot.copilot_custom_agent_short %}, that work is carried out by a subagent with its own context window. This lets the specialist focus on its assigned task without cluttering the main agent's context. You can also select a {% data variables.copilot.copilot_custom_agent_short %} for the session directly. -For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). +For more information, see [AUTOTITLE](/copilot/concepts/customizations/custom-agents). ## Creating a {% data variables.copilot.copilot_custom_agent_short %} @@ -98,7 +98,7 @@ Each {% data variables.copilot.copilot_custom_agent_short %} is defined by a Mar Enter `/agent` in interactive mode and choose from the list of available {% data variables.copilot.custom_agents_short %}. Then enter a prompt that will be passed to the selected agent. > [!NOTE] - > The CLI's default agents are not included in this list. For more information about the default agents, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents#built-in-agents). + > The CLI's default agents are not included in this list. For more information about the default agents, see [AUTOTITLE](/copilot/concepts/customizations/custom-agents#built-in-agents). * **Explicit instruction** @@ -160,7 +160,7 @@ For more information, including how this setting interacts with the `--no-custom ## Further reading -* [AUTOTITLE](/copilot/concepts/agents/copilot-cli/comparing-cli-features) +* [AUTOTITLE](/copilot/concepts/customizations/comparing-customizations) * [AUTOTITLE](/copilot/reference/custom-agents-configuration) * [AUTOTITLE](/copilot/reference/copilot-cli-reference/cli-command-reference#custom-agents-reference) * [AUTOTITLE](/copilot/tutorials/customization-library/custom-agents)—a curated collection of examples diff --git a/content/copilot/how-tos/copilot-cli/customize-copilot/overview.md b/content/copilot/how-tos/copilot-cli/customize-copilot/overview.md index 7c8b8f00485d..6fc12d63adc5 100644 --- a/content/copilot/how-tos/copilot-cli/customize-copilot/overview.md +++ b/content/copilot/how-tos/copilot-cli/customize-copilot/overview.md @@ -57,7 +57,7 @@ The Model Context Protocol (MCP) allows you to add external tools and data sourc * Book tickets online * Integrate with a calendar application -For more information, see [AUTOTITLE](/copilot/concepts/context/mcp). +For more information, see [AUTOTITLE](/copilot/concepts/customizations/mcp). ## Plugins diff --git a/content/copilot/how-tos/copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/index.md index f0d4cd6d4597..635b48c80bdd 100644 --- a/content/copilot/how-tos/copilot-cli/index.md +++ b/content/copilot/how-tos/copilot-cli/index.md @@ -5,6 +5,7 @@ intro: Use {% data variables.product.prodname_copilot_short %} directly from you versions: feature: copilot redirect_from: + - /copilot/concepts/agents/copilot-cli - /copilot/github-copilot-in-the-cli - /copilot/github-copilot-in-the-cli/configuring-github-copilot-in-the-cli - /copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli @@ -37,20 +38,20 @@ children: - /automate-copilot-cli/quickstart - /automate-copilot-cli/run-cli-programmatically - /automate-copilot-cli/schedule-prompts - - /content/copilot/concepts/agents/about-agent-skills - - /content/copilot/concepts/agents/about-plugins + - /content/copilot/concepts/customizations/agent-skills + - /content/copilot/concepts/customizations/plugins - /content/copilot/concepts/copilot-surfaces/copilot-cli - /content/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/dynamic-workflows - - /content/copilot/concepts/agents/copilot-cli/about-custom-agents + - /content/copilot/concepts/customizations/custom-agents - /content/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/about-remote-control - - /content/copilot/concepts/agents/copilot-cli/comparing-cli-features + - /content/copilot/concepts/customizations/comparing-customizations - /content/copilot/concepts/prompting-and-context/context-management - /content/copilot/concepts/agent-capabilities/agent-powered-workflows-and-operations/tool-search - /content/copilot/concepts/agent-capabilities/choosing-and-delegating-agent-work/delegating-and-parallelizing-work-with-agents - - /content/copilot/concepts/agents/copilot-cli/lsp-servers + - /content/copilot/concepts/customizations/lsp-servers - /use-copilot-cli/research-with-copilot-cli - /content/copilot/concepts/agent-capabilities/choosing-and-delegating-agent-work/getting-a-second-opinion - - /content/copilot/concepts/agents/copilot-cli/about-cli-extensions + - /content/copilot/concepts/customizations/extensions - /content/copilot/how-tos/use-copilot-agents/use-dynamic-workflows - /content/copilot/reference/copilot-cli-reference/acp-server - /content/copilot/reference/copilot-cli-reference/cli-command-reference diff --git a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md index f9e6e4cd37fc..838a570370f3 100644 --- a/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md +++ b/content/copilot/how-tos/copilot-cli/set-up-copilot-cli/add-lsp-servers.md @@ -14,7 +14,7 @@ category: ## Introduction -This article explains how to add LSP servers for {% data variables.copilot.copilot_cli_short %}. For conceptual information about LSP servers, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/lsp-servers). +This article explains how to add LSP servers for {% data variables.copilot.copilot_cli_short %}. For conceptual information about LSP servers, see [AUTOTITLE](/copilot/concepts/customizations/lsp-servers). Adding an LSP server for {% data variables.copilot.copilot_cli_short %} is a two-step process: diff --git a/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/configure-toolsets.md b/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/configure-toolsets.md index 49aa5605ca81..a068aec818bf 100644 --- a/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/configure-toolsets.md +++ b/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/configure-toolsets.md @@ -22,7 +22,7 @@ The {% data variables.product.github %} MCP server includes default toolsets (`r * **Accessing remote-only toolsets** such as `copilot` (for {% data variables.copilot.copilot_cloud_agent %}) and `github_support_docs_search`, which are only available on the remote MCP server * **Selecting specific tools** for granular control when you want to exclude specific tools or combine toolsets with individual tools -For a complete list of available toolsets, see [Tools](https://github.com/github/github-mcp-server/blob/main/README.md#tools) in the `github/github-mcp-server` repository. For configuration examples, see [Server configuration](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md). For a full introduction to the {% data variables.product.github %} MCP server and an overview of MCP, see [AUTOTITLE](/copilot/concepts/context/mcp). +For a complete list of available toolsets, see [Tools](https://github.com/github/github-mcp-server/blob/main/README.md#tools) in the `github/github-mcp-server` repository. For configuration examples, see [Server configuration](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md). For a full introduction to the {% data variables.product.github %} MCP server and an overview of MCP, see [AUTOTITLE](/copilot/concepts/customizations/mcp). ## Configuring toolsets for the remote MCP server diff --git a/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp.md b/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp.md index 2d1a5ecc3cdb..083500b6c744 100644 --- a/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp.md +++ b/content/copilot/how-tos/copilot-in-your-ide/customize-copilot/extend-copilot-with-tools-and-context/extend-copilot-chat-with-mcp.md @@ -22,7 +22,7 @@ category: ## Introduction -The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). For an overview of MCP, see [AUTOTITLE](/copilot/concepts/context/mcp). +The Model Context Protocol (MCP) is an open standard that defines how applications share context with large language models (LLMs). For an overview of MCP, see [AUTOTITLE](/copilot/concepts/customizations/mcp). For a curated list of MCP servers from partners and the community, see the [{% data variables.product.github %} MCP Registry](https://github.com/mcp). diff --git a/content/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-custom-agents.md b/content/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-custom-agents.md index ffff1c7bcdfb..48bcb813506f 100644 --- a/content/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-custom-agents.md +++ b/content/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-custom-agents.md @@ -12,7 +12,7 @@ redirect_from: - /copilot/how-tos/use-copilot-agents/cloud-agent/create-custom-agents-in-your-ide --- -{% data variables.copilot.custom_agents_caps_short %} allow you to tailor {% data variables.product.prodname_copilot_short %}'s expertise for specific tasks. For a conceptual overview of {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). +{% data variables.copilot.custom_agents_caps_short %} allow you to tailor {% data variables.product.prodname_copilot_short %}'s expertise for specific tasks. For a conceptual overview of {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/concepts/customizations/custom-agents). {% data reusables.copilot.custom-agents-ide-preview %} diff --git a/content/copilot/how-tos/copilot-on-github/copilot-for-github-tasks/using-the-github-mcp-server-from-copilot-chat.md b/content/copilot/how-tos/copilot-on-github/copilot-for-github-tasks/using-the-github-mcp-server-from-copilot-chat.md index b939952d5a07..cb9ab5d09a02 100644 --- a/content/copilot/how-tos/copilot-on-github/copilot-for-github-tasks/using-the-github-mcp-server-from-copilot-chat.md +++ b/content/copilot/how-tos/copilot-on-github/copilot-for-github-tasks/using-the-github-mcp-server-from-copilot-chat.md @@ -14,7 +14,7 @@ redirect_from: The {% data variables.product.github %} MCP server is pre-configured in {% data variables.copilot.copilot_chat_dotcom_short %} with a limited set of skills, so you can use it immediately. Instruct {% data variables.copilot.copilot_chat_short %} to perform tasks like creating branches or merging pull requests on your behalf. -For a full list of available skills, see [AUTOTITLE](/copilot/reference/chat-cheat-sheet#mcp-skills). For more about MCP, see [AUTOTITLE](/copilot/concepts/context/mcp). +For a full list of available skills, see [AUTOTITLE](/copilot/reference/chat-cheat-sheet#mcp-skills). For more about MCP, see [AUTOTITLE](/copilot/concepts/customizations/mcp). ## Use the {% data variables.product.github %} MCP server diff --git a/content/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers.md b/content/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers.md index c68c600cff21..6beb3bdd4df6 100644 --- a/content/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers.md +++ b/content/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers.md @@ -22,7 +22,7 @@ category: ## Prerequisite -Before setting up MCP servers for your repository, read [AUTOTITLE](/copilot/concepts/context/mcp) and [AUTOTITLE](/copilot/concepts/agents/cloud-agent/mcp-and-cloud-agent). +Before setting up MCP servers for your repository, read [AUTOTITLE](/copilot/concepts/customizations/mcp). ## Introduction diff --git a/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents.md b/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents.md index 4add7c99c6cc..1a3007b02a44 100644 --- a/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents.md +++ b/content/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents.md @@ -14,7 +14,7 @@ redirect_from: - /copilot/how-tos/use-copilot-agents/cloud-agent/create-custom-agents --- -{% data variables.copilot.custom_agents_caps_short %} allow you to tailor {% data variables.product.prodname_copilot_short %}'s expertise for specific tasks. For a conceptual overview of {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). +{% data variables.copilot.custom_agents_caps_short %} allow you to tailor {% data variables.product.prodname_copilot_short %}'s expertise for specific tasks. For a conceptual overview of {% data variables.copilot.custom_agents_short %}, see [AUTOTITLE](/copilot/concepts/customizations/custom-agents). {% data reusables.copilot.custom-agents-ide-preview %} diff --git a/content/copilot/how-tos/copilot-on-github/set-up-copilot/enable-copilot/set-up-for-teachers-and-os-maintainers.md b/content/copilot/how-tos/copilot-on-github/set-up-copilot/enable-copilot/set-up-for-teachers-and-os-maintainers.md index 3da40e15664a..36bea6e5cc16 100644 --- a/content/copilot/how-tos/copilot-on-github/set-up-copilot/enable-copilot/set-up-for-teachers-and-os-maintainers.md +++ b/content/copilot/how-tos/copilot-on-github/set-up-copilot/enable-copilot/set-up-for-teachers-and-os-maintainers.md @@ -32,7 +32,7 @@ There are two ways to qualify for free access to {% data variables.copilot.copil If you do not meet the previous criteria, you can do one of the following: -* Subscribe to [{% data variables.copilot.copilot_pro_short %}](https://github.com/github-copilot/signup?ref_product=copilot&ref_type=purchase&ref_style=text&ref_plan=pro), [{% data variables.copilot.copilot_pro_plus_short %}](https://github.com/github-copilot/signup?ref_product=copilot&ref_type=purchase&ref_style=text&ref_plan=pro), or [{% data variables.copilot.copilot_max_short %}](https://github.com/settings/billing/licensing?ref_product=copilot&ref_type=purchase&ref_style=text&ref_plan=max) for a paid plan with access to premium models. +* Subscribe to [{% data variables.copilot.copilot_pro_short %}](https://github.com/github-copilot/signup?ref_product=copilot&ref_type=purchase&ref_style=text&ref_plan=pro), [{% data variables.copilot.copilot_pro_plus_short %}](https://github.com/github-copilot/signup?ref_product=copilot&ref_type=purchase&ref_style=text&ref_plan=pro-plus), or [{% data variables.copilot.copilot_max_short %}](https://github.com/settings/billing/licensing?ref_product=copilot&ref_type=purchase&ref_style=text&ref_plan=max) for a paid plan with access to premium models. * Set up {% data variables.copilot.copilot_free_short %} to get a limited experience of {% data variables.product.prodname_copilot_short %} without a paid plan. See [AUTOTITLE](/copilot/get-started/plans). ## Accessing {% data variables.copilot.copilot_pro_short %} for free diff --git a/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md b/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md index 2e7ea8abdac0..4fb1719aa428 100644 --- a/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md +++ b/content/copilot/how-tos/github-copilot-app/customize-github-copilot-app.md @@ -75,7 +75,7 @@ Use the agent picker dropdown in the prompt box to select a {% data variables.co Alternatively, type `/agent` in the prompt box to choose and invoke a {% data variables.copilot.copilot_custom_agent_short %}. -For more information, see [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). +For more information, see [AUTOTITLE](/copilot/concepts/customizations/custom-agents). ## Adding plugins diff --git a/content/copilot/how-tos/use-copilot-agents/cloud-agent/index.md b/content/copilot/how-tos/use-copilot-agents/cloud-agent/index.md index 0bc086be4327..ec241a511954 100644 --- a/content/copilot/how-tos/use-copilot-agents/cloud-agent/index.md +++ b/content/copilot/how-tos/use-copilot-agents/cloud-agent/index.md @@ -30,4 +30,4 @@ redirect_from: contentType: how-tos --- -These articles provide how-to information for using {% data variables.copilot.copilot_cloud_agent %}. For an overview of {% data variables.copilot.copilot_cloud_agent %}, see the articles under [AUTOTITLE](/copilot/concepts/agents/cloud-agent). +These articles provide how-to information for using {% data variables.copilot.copilot_cloud_agent %}. For an overview of {% data variables.copilot.copilot_cloud_agent %}, see [AUTOTITLE](/copilot/concepts/copilot-surfaces/copilot-on-github). diff --git a/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md b/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md index cd7fd05dc469..18edd3c3cb95 100644 --- a/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md +++ b/content/copilot/reference/copilot-billing/request-based-billing-legacy/github-copilot-premium-requests.md @@ -72,7 +72,7 @@ If you run out of free minutes or premium requests, and you have _not_ set up bi {% data variables.copilot.copilot_cloud_agent %} uses a dedicated {% data variables.copilot.copilot_cloud_agent %} premium request SKU. This SKU still pulls from your monthly allowance of premium requests, but allows for more granular budget control and monitoring. -For more information about {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_custom_agents %}, see [AUTOTITLE](/copilot/concepts/copilot-surfaces/copilot-on-github) and [AUTOTITLE](/copilot/concepts/agents/cloud-agent/about-custom-agents). +For more information about {% data variables.copilot.copilot_cloud_agent %} and {% data variables.copilot.copilot_custom_agents %}, see [AUTOTITLE](/copilot/concepts/copilot-surfaces/copilot-on-github) and [AUTOTITLE](/copilot/concepts/customizations/custom-agents). ## Using more than your included premium requests diff --git a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md index ab98192e8121..f199be6f4fdd 100644 --- a/content/copilot/reference/copilot-cli-reference/cli-command-reference.md +++ b/content/copilot/reference/copilot-cli-reference/cli-command-reference.md @@ -539,7 +539,7 @@ These are the slash commands you can use from within an interactive CLI session. |-----------------------------------------------------|---------| | `/add-dir PATH` | Allow file access to a directory and load its `.github/skills` and `.github/agents` as trusted configurations. When sandboxing is enabled, also grants the sandbox access to the directory for the current session. | | `/after [DELAY PROMPT]`, `/after` | Schedule a non-recurring prompt, skill, or schedulable slash command for the current session (for example, `/after 30m remind me the time` or `/after 1h /chronicle standup`). With no arguments the schedule manager is displayed. {% data reusables.copilot.experimental %} | -| `/agent` | Browse and select from available agents (if any). See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). | +| `/agent` | Browse and select from available agents (if any). See [AUTOTITLE](/copilot/concepts/customizations/custom-agents). | | `/app` | Open the current session in the {% data variables.copilot.github_copilot_app %} (requires version 1.1.3 or later), or show the download URL if the app is not installed. | | `/ask [QUESTION]`, `/btw [QUESTION]` | Ask a quick side question without adding to the conversation history. The response renders as Markdown. In the answer dialog, press Ctrl+E to expand it and Ctrl+Y to copy the full answer. Enter the command without a question to reopen the last side question answer in the current session. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli/ask-a-side-question). | | `/allow-all [off\|auto\|show]`, `/yolo [off\|auto\|show]` | Enable all permissions (tools, paths, and URLs). This is an alias for `/permissions allow-all`; see the `/permissions` row for the canonical command and its subcommands. | @@ -666,7 +666,7 @@ Use `/collect-debug-logs [file|gist|share] [PATH]` to gather debug logs for trou | `--add-github-mcp-tool=TOOL` | Add a tool to enable for the {% data variables.product.github %} MCP server, instead of the default CLI subset (can be used multiple times). Use `*` for all tools. | | `--add-github-mcp-toolset=TOOLSET` | Add a toolset to enable for the {% data variables.product.github %} MCP server, instead of the default CLI subset (can be used multiple times). Use `all` for all toolsets. | | `--additional-mcp-config=JSON` | Add an MCP server for this session only. The server configuration can be supplied as a JSON string or a file path (prefix with `@`). A relative `@file` path resolves against the session working directory (the `--resume`, `--worktree`, or `-C` directory), regardless of option order. Augments the configuration from `~/.copilot/mcp-config.json`. Overrides any installed MCP server configuration with the same name. See [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). | -| `--agent=AGENT` | Specify a {% data variables.copilot.copilot_custom_agent_short %} to use. See [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents). | +| `--agent=AGENT` | Specify a {% data variables.copilot.copilot_custom_agent_short %} to use. See [AUTOTITLE](/copilot/concepts/customizations/custom-agents). | | `--allow-all` | Enable all permissions (equivalent to `--allow-all-tools --allow-all-paths --allow-all-urls`). | | `--allow-all-mcp-server-instructions` | Include initialization instructions from all MCP servers in the system prompt. By default, only allowlisted server instructions are included up front; other servers' instructions are retrieved on demand. | | `--allow-all-paths` | Disable file path verification and allow access to any path. | @@ -1344,6 +1344,32 @@ Installing a directory registers it as a custom skill source rather than copying Commands are an alternative to skills stored as individual `.md` files in `.claude/commands/`. The command name is derived from the filename. Command files use a simplified format (no `name` field required) and support `argument-hint`, `description`, `allowed-tools`, and `disable-model-invocation`. Commands have lower priority than skills with the same name. +## Extension modes + +{% data reusables.copilot.copilot-cli.cli-extensions-experimental %} + +In an interactive session, `/extensions mode` controls whether extensions run and whether {% data variables.product.prodname_copilot_short %} can manage them. + +| Mode | Extensions run | Agent can manage extensions | +| --- | --- | --- | +| **Load & Augment** (default) | Yes | Yes | +| **Load Only** | Yes | No | +| **Disabled** | No | No | + +In **Load & Augment** mode, the agent has tools to list discovered extensions, inspect their status and logs, scaffold a starter extension, and reload extensions after code changes. This lets the agent create and load extension code as part of your request. + +Choose **Load Only** to run an existing set of trusted extensions without giving the agent extension-management tools. The agent can still call tools supplied by running extensions. + +Mode changes take effect immediately in the current session: + +* Switching to **Disabled** stops running extension processes and removes their tools. +* Switching from **Disabled** to either loading mode starts extensions. +* Switching between **Load Only** and **Load & Augment** changes access to extension-management tools without stopping the extensions. + +Disabling extensions persists for future sessions until you choose a loading mode. Other sessions that are already running are not affected. + +To inspect extensions and their status, use `/extensions manage`. For discovery locations and implementation examples, see [AUTOTITLE](/copilot/tutorials/create-an-extension). + ## Custom agents reference Custom agents are specialized AI agents defined in Markdown files. For user, project, and added-root agents, the agent ID is derived from the file's path relative to the `agents` directory. The CLI removes the `.agent.md` or `.md` extension and replaces directory separators with `--`. For example, `agents/team/reviewer.agent.md` has the ID `team--reviewer`. diff --git a/content/copilot/reference/customization-cheat-sheet.md b/content/copilot/reference/customization-cheat-sheet.md index 7ecec9cc6eae..d542a89806f8 100644 --- a/content/copilot/reference/customization-cheat-sheet.md +++ b/content/copilot/reference/customization-cheat-sheet.md @@ -19,11 +19,11 @@ This table shows what each customization feature is and where it lives. |---------|-----------|-------------------| | [Custom instructions](/copilot/concepts/prompting-and-context/custom-instructions) | Always-on context that automatically applies to every interaction within its defined scope | `.github/copilot-instructions.md` (repo-wide), `.github/instructions/*.instructions.md` (path-specific), `AGENTS.md` (third-party agents), or personal/org settings via UI on {% data variables.product.github %} | | [Prompt files](/copilot/concepts/prompting-and-context/prompt-files) | Reusable, standalone prompt template with input variables | `.github/prompts/*.prompt.md` | -| [{% data variables.copilot.custom_agents_caps_short %}](/copilot/concepts/agents/cloud-agent/about-custom-agents) | Specialist persona with its own instructions, tool restrictions, and context | `.github/agents/AGENT-NAME.md` (repository), `/agents/AGENT-NAME.md` in the organization's `.github` or `.github-private` repository (org-level), `/agents/AGENT-NAME.md` in a designated `.github-private` repository (enterprise-level), or user profile | +| [AUTOTITLE](/copilot/concepts/customizations/custom-agents) | Specialist persona with its own instructions, tool restrictions, and context | `.github/agents/AGENT-NAME.md` (repository), `/agents/AGENT-NAME.md` in the organization's `.github` or `.github-private` repository (org-level), `/agents/AGENT-NAME.md` in a designated `.github-private` repository (enterprise-level), or user profile | | [{% data variables.copilot.subagents_caps_short %}](/copilot/how-tos/copilot-in-your-ide/use-copilot-agents/use-subagents) | Separate agent spawned by the main agent to handle delegated work in an isolated context | N/A (runtime process, not a user-configured file) | | [Agent skills](/copilot/concepts/agents/about-agent-skills) | Folder of instructions, scripts, and resources that {% data variables.product.prodname_copilot_short %} loads when relevant to a task | `.github/skills/
') && html.endsWith('
')) { - return fastTextOnly(html.slice(3, -4)) - } - return fastTextOnly(html) - }), - })) + changes + // Older changelog data has schema groups with no changes. + .filter((change) => change.changes.length > 0) + .map((change) => ({ + title: change.title, + changes: change.changes.map((html: string) => { + if (html.startsWith('') && html.endsWith('
')) { + return fastTextOnly(html.slice(3, -4)) + } + return fastTextOnly(html) + }), + })) return { date: item.date, diff --git a/src/article-api/transformers/graphql-reference-transformer.ts b/src/article-api/transformers/graphql-reference-transformer.ts index 5425f179e345..8335f91b0ab5 100644 --- a/src/article-api/transformers/graphql-reference-transformer.ts +++ b/src/article-api/transformers/graphql-reference-transformer.ts @@ -173,6 +173,7 @@ export class GraphQLReferenceTransformer implements PageTransformer { type: arg.type, href: arg.href, description: arg.description ? fastTextOnly(arg.description) : '', + defaultValue: arg.defaultValue, })), } } diff --git a/src/article-api/transformers/release-notes-transformer.ts b/src/article-api/transformers/release-notes-transformer.ts index fca2dc76d612..498cd7624254 100644 --- a/src/article-api/transformers/release-notes-transformer.ts +++ b/src/article-api/transformers/release-notes-transformer.ts @@ -50,8 +50,14 @@ const SECTION_LABELS: Record{item === null ? null : item}
+
+ {item === null ? (
+ null
+ ) : typeof item === 'string' ? (
+ item
+ ) : (
+ // React renders nothing for boolean children.
+ JSON.stringify(item)
+ )}
+
{index !== array.length - 1 && ','}{' '}
))}
@@ -127,9 +125,10 @@ export function ParameterRow({
/>
)}
- {/* Empty child groups mark unloaded nested params except shared webhook props; details lazy-loads them. */}
- {rowParams.type &&
- (rowParams.type.includes('object') || rowParams.type.includes('array of')) &&
+ {/* Empty child groups mark unloaded webhook objects except shared props; only rows with a callback can load them. */}
+ {bodyParamExpandCallback &&
+ rowParams.type &&
+ rowParams.type.includes('object') &&
rowParams.childParamsGroups &&
rowParams.childParamsGroups.length === 0 &&
!NO_CHILD_WEBHOOK_PROPERTIES.includes(rowParams.name) ? (
@@ -139,10 +138,7 @@ export function ParameterRow({
data-nested-param-id={rowParams.name}
className="box px-3 ml-1 mb-0"
onToggle={(event) => {
- if (bodyParamExpandCallback) {
- const target = event.target as HTMLDetailsElement
- bodyParamExpandCallback(target)
- }
+ bodyParamExpandCallback(event.target as HTMLDetailsElement)
}}
>
true')
+ })
+
+ test('renders false', () => {
+ expect(renderEnum([false])).toContain('false')
+ })
+
+ test('renders strings without quotes', () => {
+ const html = renderEnum(['open', 'closed'])
+ expect(html).toContain('open')
+ expect(html).toContain('closed')
+ })
+
+ test('renders null in italics', () => {
+ expect(renderEnum([null])).toContain('null')
+ })
+})
diff --git a/src/codeql-cli/README.md b/src/codeql-cli/README.md
index dac5c28c25ba..561950465a59 100644
--- a/src/codeql-cli/README.md
+++ b/src/codeql-cli/README.md
@@ -55,7 +55,7 @@ If you have a question about the CodeQL CLI pipeline, you can ask in the `#techn
|------------|---------|--------------|-------|
| **Pandoc** | Convert ReStructuredText to Markdown | `brew install pandoc` (macOS) | Version 2.x+ required |
| **semmle-code repo** | Source ReStructuredText files | Clone at root of docs-internal | Private GitHub repo |
-| **Node.js** | Run sync script | Already in project | Version specified in `.nvmrc` |
+| **Node.js** | Run sync script | Already in project | Version specified in `engines.node` in `package.json` |
### Source data location
- **Repository**: `github/semmle-code` (private)
diff --git a/src/codeql-cli/scripts/convert-markdown-for-docs.ts b/src/codeql-cli/scripts/convert-markdown-for-docs.ts
index 97d13dd4b964..05cf108e3b1e 100644
--- a/src/codeql-cli/scripts/convert-markdown-for-docs.ts
+++ b/src/codeql-cli/scripts/convert-markdown-for-docs.ts
@@ -3,6 +3,7 @@ import path from 'path'
import { fromMarkdown } from 'mdast-util-from-markdown'
import { toMarkdown } from 'mdast-util-to-markdown'
+import { toString } from 'mdast-util-to-string'
import { visitParents } from 'unist-util-visit-parents'
import { visit, SKIP } from 'unist-util-visit'
import { remove } from 'unist-util-remove'
@@ -90,6 +91,7 @@ export async function convertContentToDocs(
})
let currentNodeIsDescription = false
+ let descriptionParagraph: MdNode | undefined
visit(ast, (rawNode) => {
const node = rawNode as unknown as MdNode
// A bare return is CONTINUE. Returning false would mean EXIT,
@@ -101,7 +103,7 @@ export async function convertContentToDocs(
currentNodeIsDescription = true
}
if (currentNodeIsDescription && node.type === 'paragraph') {
- frontmatter.intro = node.children[0]?.value
+ descriptionParagraph = node
currentNodeIsDescription = false
return SKIP
}
@@ -146,6 +148,10 @@ export async function convertContentToDocs(
(node.value.startsWith('-') || node.value.startsWith('<'))
) {
node.type = 'inlineCode'
+ // Placeholders like 
\n 
\n1. Next step.\n',
+ )
+ const $ = load(html)
+ expect($('.procedural-image-wrapper')).toHaveLength(2)
+ expect($('.procedural-image-wrapper .procedural-image-wrapper')).toHaveLength(0)
+ const srcs = imgSrcs($)
+ expect(srcs.filter((src) => src.includes('a.png'))).toHaveLength(1)
+ expect(srcs.filter((src) => src.includes('b.png'))).toHaveLength(1)
+ })
+
+ test('does not wrap a loose list image inside a paragraph', async () => {
+ const html = await renderContent(
+ '1. Click **Settings**.\n\n \n\n1. Next step.\n',
+ )
+ const $ = load(html)
+ expect($('.procedural-image-wrapper')).toHaveLength(0)
+ expect($('li p img').attr('src')).toContain('a.png')
+ })
+})
diff --git a/src/content-render/unified/processor.ts b/src/content-render/unified/processor.ts
index 735a58566ec7..4ac6aadad296 100644
--- a/src/content-render/unified/processor.ts
+++ b/src/content-render/unified/processor.ts
@@ -32,6 +32,9 @@ import annotate from './annotate'
import alerts from './alerts'
import removeHtmlComments from 'remark-remove-comments'
import remarkStringify from 'remark-stringify'
+import { visit } from 'unist-util-visit'
+import type { Parents, Root, Text } from 'mdast'
+import type { Info, State } from 'mdast-util-to-markdown'
import type { Context, UnifiedProcessor } from '@/content-render/types'
import type { CollectedHeading } from '@/frame/lib/get-mini-toc-items'
@@ -84,12 +87,49 @@ export function createMarkdownOnlyProcessor(context: Context): UnifiedProcessor
unified()
.use(remarkParse)
.use(gfm)
+ .use(markUnescapedAlertMarkers)
// TypeScript's unified plugin types do not model context-bound transformer factories.
.use(rewriteLocalLinks as unknown as (ctx: Context) => void, context)
- .use(remarkStringify) as unknown as UnifiedProcessor
+ .use(remarkStringify, {
+ handlers: { text: textWithAlertMarkers },
+ }) as unknown as UnifiedProcessor
)
}
+// GitHub alert markers stop rendering as alerts once remark-stringify escapes their brackets.
+const ALERT_MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](?=\s|$)/i
+
+// remark-parse drops the backslash from `\[!NOTE]`, so only the source shows an intentionally literal marker.
+const unescapedAlertMarkers = new WeakSet
+ & {
+ implements?: Pick[]
+}
+
export type EnumValuesT = {
name: string
description: string
diff --git a/src/graphql/data/ghec/schema-other.json b/src/graphql/data/ghec/schema-other.json
index 6d5185f37a30..4ff518042191 100644
--- a/src/graphql/data/ghec/schema-other.json
+++ b/src/graphql/data/ghec/schema-other.json
@@ -100,7 +100,7 @@
"name": "Boolean",
"description": "
@@ -52,7 +55,7 @@ export default function GraphqlReferencePage({
}
export const getServerSideProps: GetServerSideProps = async (context) => {
- const { getGraphqlSchema, getAllGraphqlObjects } = await import('@/graphql/lib/index')
+ const { getGraphqlSchema, getGraphqlInterfaceImplementers } = await import('@/graphql/lib/index')
const req = context.req as unknown as ExtendedRequest
const res = context.res
@@ -69,7 +72,6 @@ export const getServerSideProps: GetServerSideProps = async (context) =>
}
const schema = getGraphqlSchema(currentVersion, page) as CategorySchema
- const allObjects = getAllGraphqlObjects(currentVersion) as ObjectT[]
// Return 404 when a version has no types because the route can serve categories without files.
const hasAnyTypes = ALL_KIND_KEYS.some((kind) => {
@@ -80,14 +82,17 @@ export const getServerSideProps: GetServerSideProps = async (context) =>
return { notFound: true }
}
+ const implementers = getGraphqlInterfaceImplementers(
+ currentVersion,
+ (schema.interfaces ?? []).map((item) => item.name),
+ )
+
// Build nested kind entries because MiniTocs recurses and default collection stops at one level.
const automatedPageContext = getAutomatedPageContextFromRequest(req)
for (const kind of ALL_KIND_KEYS) {
const kindItems = (schema as Record>)[kind]
if (!kindItems || kindItems.length === 0) continue
- const sortedItems = [...kindItems].sort((a, b) =>
- a.name.toLowerCase().localeCompare(b.name.toLowerCase()),
- )
+ const sortedItems = [...kindItems].sort(compareByName)
automatedPageContext.miniTocItems.push({
contents: {
href: `#${KIND_URL_SEGMENT[kind]}`,
@@ -110,7 +115,7 @@ export const getServerSideProps: GetServerSideProps = async (context) =>
mainContext,
automatedPageContext,
schema,
- allObjects,
+ implementers,
language,
categorySlug: page,
},
diff --git a/src/graphql/scripts/build-changelog.ts b/src/graphql/scripts/build-changelog.ts
index a52c42dbfdd2..8d5690085cfd 100644
--- a/src/graphql/scripts/build-changelog.ts
+++ b/src/graphql/scripts/build-changelog.ts
@@ -167,17 +167,19 @@ export async function createChangelogEntry(
upcomingChanges: [],
}
- const cleanedSchemaChanges = cleanMessagesFromChanges(schemaChangesToReport)
- const renderedScheamChanges = await Promise.all(
- cleanedSchemaChanges.map(async (change): Promise => {
- return await renderContent(change)
- }),
- )
- const schemaChange: ChangelogSchemaChange = {
- title: 'The GraphQL schema includes these changes:',
- changes: renderedScheamChanges,
+ if (schemaChangesToReport.length > 0) {
+ const cleanedSchemaChanges = cleanMessagesFromChanges(schemaChangesToReport)
+ const renderedScheamChanges = await Promise.all(
+ cleanedSchemaChanges.map(async (change): Promise => {
+ return await renderContent(change)
+ }),
+ )
+ const schemaChange: ChangelogSchemaChange = {
+ title: 'The GraphQL schema includes these changes:',
+ changes: renderedScheamChanges,
+ }
+ changelogEntry.schemaChanges.push(schemaChange)
}
- changelogEntry.schemaChanges.push(schemaChange)
for (const previewTitle in previewChangesToReport) {
const previewChanges = previewChangesToReport[previewTitle]
diff --git a/src/graphql/scripts/utils/process-schemas.ts b/src/graphql/scripts/utils/process-schemas.ts
index 034691b44248..d415670c3485 100755
--- a/src/graphql/scripts/utils/process-schemas.ts
+++ b/src/graphql/scripts/utils/process-schemas.ts
@@ -960,7 +960,8 @@ export default async function processSchemas(
}),
)
- data.scalars = sortBy(data.scalars.concat(externalScalars), 'name')
+ // Copies keep in-place href rewriting in bucketing from compounding across versions.
+ data.scalars = sortBy(data.scalars.concat(externalScalars.map((s) => ({ ...s }))), 'name')
data.queries = sortBy(data.queries, 'name')
data.mutations = sortBy(data.mutations, 'name')
diff --git a/src/graphql/scripts/utils/schema-helpers.ts b/src/graphql/scripts/utils/schema-helpers.ts
index 4cbf514a967b..2f47582d1d18 100644
--- a/src/graphql/scripts/utils/schema-helpers.ts
+++ b/src/graphql/scripts/utils/schema-helpers.ts
@@ -52,7 +52,8 @@ const graphqlTypes: GraphQLTypeInfo[] = JSON.parse(
await fs.readFile(path.join(process.cwd(), './src/graphql/lib/types.json'), 'utf-8'),
)
-const singleQuotesInsteadOfBackticks = / '(\S+?)' /
+// Lookarounds keep the surrounding spaces out of the match so the replacement does not drop them.
+const singleQuotesInsteadOfBackticks = /(?<= )'(\S+?)'(?= )/g
// Upstream schema descriptions include ${externalDocsUrl}, but this pipeline never expands it.
// It ships as href="$%7BexternalDocsUrl%7D/code-security/..." and resolves against the
diff --git a/src/graphql/tests/build-changelog.ts b/src/graphql/tests/build-changelog.ts
index 14d1a50c2604..45ef31199011 100644
--- a/src/graphql/tests/build-changelog.ts
+++ b/src/graphql/tests/build-changelog.ts
@@ -208,6 +208,69 @@ upcoming_changes:
)
expect(nullEntry).toBeNull()
})
+
+ test('omits the schema changes group when only upcoming changes exist', async () => {
+ const schemaString = `
+ type Query {
+ i: Int!
+ }`
+
+ const entry: ChangelogEntry | null = await createChangelogEntry(
+ schemaString,
+ schemaString,
+ [],
+ [],
+ [
+ {
+ location: 'Query.i',
+ description: '`i` will be removed.',
+ date: '2021-06-01T00:00:00+00:00',
+ },
+ ],
+ )
+ expect(entry).not.toBeNull()
+ expect(entry!.schemaChanges).toEqual([])
+ expect(entry!.upcomingChanges).toHaveLength(1)
+ })
+
+ test('omits the schema changes group when only preview changes exist', async () => {
+ const oldSchemaString = `
+ type PreviewType {
+ a: Int
+ }
+
+ type Query {
+ previewField: PreviewType
+ }`
+
+ const newSchemaString = `
+ type PreviewType {
+ a: Int
+ b: Int
+ }
+
+ type Query {
+ previewField: PreviewType
+ }`
+
+ const previews = [
+ {
+ title: 'Test preview',
+ toggled_on: ['PreviewType'],
+ },
+ ]
+
+ const entry: ChangelogEntry | null = await createChangelogEntry(
+ oldSchemaString,
+ newSchemaString,
+ previews,
+ [],
+ [],
+ )
+ expect(entry).not.toBeNull()
+ expect(entry!.schemaChanges).toEqual([])
+ expect(entry!.previewChanges).toHaveLength(1)
+ })
})
describe('Preparing preview links', () => {
diff --git a/src/graphql/tests/categories.ts b/src/graphql/tests/categories.ts
new file mode 100644
index 000000000000..59443af1c125
--- /dev/null
+++ b/src/graphql/tests/categories.ts
@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+
+import { compareByName } from '@/graphql/lib/categories'
+
+describe('compareByName', () => {
+ afterEach(() => {
+ vi.restoreAllMocks()
+ })
+
+ // Czech collation sorts "ch" after "h", so an unpinned locale reorders names in a Czech browser.
+ test('sorts the same way when the default locale is Czech', () => {
+ const original = String.prototype.localeCompare
+ vi.spyOn(String.prototype, 'localeCompare').mockImplementation(function (
+ this: string,
+ that: string,
+ locales?: Intl.LocalesArgument,
+ options?: Intl.CollatorOptions,
+ ) {
+ return original.call(this, that, locales ?? 'cs', options)
+ })
+
+ const inputs = [{ name: 'CreateCheckRunInput' }, { name: 'CheckAnnotationData' }]
+ expect(inputs.sort(compareByName).map((item) => item.name)).toEqual([
+ 'CheckAnnotationData',
+ 'CreateCheckRunInput',
+ ])
+
+ const mutations = [{ name: 'followUser' }, { name: 'changeUserStatus' }]
+ expect(mutations.sort(compareByName).map((item) => item.name)).toEqual([
+ 'changeUserStatus',
+ 'followUser',
+ ])
+ })
+})
diff --git a/src/graphql/tests/derive-categories.ts b/src/graphql/tests/derive-categories.ts
index 4a0b675d88b8..5662d4d8733f 100644
--- a/src/graphql/tests/derive-categories.ts
+++ b/src/graphql/tests/derive-categories.ts
@@ -1,6 +1,7 @@
import { describe, expect, test } from 'vitest'
import processSchemas from '../scripts/utils/process-schemas'
+import { bucketSchemaByCategory } from '@/graphql/scripts/utils/bucket-by-category'
// Minimal @docsCategory lets buildASTSchema parse fixtures and mirrors github/github output.
const DIRECTIVE = `
@@ -145,3 +146,15 @@ describe('reference-based category derivation (PASS 1.5 rule c)', () => {
expect(cats.MutationArgEnum).toBe('repos')
})
})
+
+describe('built-in scalar hrefs', () => {
+ test('stay stable across repeated processSchemas and bucketing runs', async () => {
+ // sync.ts processes every version in one process, and bucketing rewrites hrefs in place.
+ for (let pass = 0; pass < 3; pass++) {
+ const data = await processSchemas(QUERY, [])
+ bucketSchemaByCategory(data)
+ const boolean = data.scalars.find((s) => s.name === 'Boolean')
+ expect(boolean?.href).toBe('/graphql/reference/other#scalar-boolean')
+ }
+ })
+})
diff --git a/src/graphql/tests/description-links.ts b/src/graphql/tests/description-links.ts
index 1f07d84e5aca..61eed4767383 100644
--- a/src/graphql/tests/description-links.ts
+++ b/src/graphql/tests/description-links.ts
@@ -51,3 +51,22 @@ describe('GraphQL description links', () => {
expect(offenders).toEqual([])
})
})
+
+describe('GraphQL description quoted words', () => {
+ test('keeps the spaces around a quoted word turned into code', async () => {
+ const rendered = await helpers.getDescription(
+ "Represents a 'deployed' event on a given pull request",
+ )
+
+ expect(rendered).toContain('a {
+ if (!needsRendering(value)) return value
+ try {
+ return await executeWithFallback(
+ context,
+ () => renderContent(value, context, { textOnly: true }),
+ (enContext: Context) => renderContent(value, enContext, { textOnly: true }),
+ )
+ } catch {
+ // executeWithFallback rethrows non-fallbackable errors and all English content errors.
+ return value
+ }
+}
+
function getJourneyPages(pages: Record): JourneyPage[] {
if (!cachedJourneyPages) {
cachedJourneyPages = (Object.values(pages) as JourneyPage[]).filter(
@@ -229,7 +243,7 @@ export async function resolveJourneyContext(
result = {
trackId: track.id,
trackName: track.id,
- trackTitle: track.title,
+ trackTitle: await renderTextField(track.title, context),
journeyTitle: journeyPage.title || '',
journeyPath:
journeyPage.permalink || Permalink.relativePathToSuffix(journeyPage.relativePath || ''),
@@ -261,7 +275,7 @@ export async function resolveJourneyContext(
if (guideData) {
result.nextTrackFirstGuide = {
...guideData,
- trackTitle: nextTrack.title,
+ trackTitle: await renderTextField(nextTrack.title, context),
}
}
}
diff --git a/src/journeys/tests/journey-path-resolver.ts b/src/journeys/tests/journey-path-resolver.ts
index e7afb804e4ad..3cff7f75ae26 100644
--- a/src/journeys/tests/journey-path-resolver.ts
+++ b/src/journeys/tests/journey-path-resolver.ts
@@ -33,11 +33,16 @@ vi.mock('@/content-render/index', () => ({
}))
vi.mock('@/languages/lib/render-with-fallback', () => ({
- executeWithFallback: async (fn: () => Promise, fallback: () => string) => {
+ executeWithFallback: async (
+ context: { currentLanguage?: string },
+ fn: () => Promise,
+ fallback: (enContext: unknown) => string | Promise,
+ ) => {
try {
return await fn()
- } catch {
- return fallback()
+ } catch (error) {
+ if (context.currentLanguage === 'en') throw error
+ return fallback({ ...context, currentLanguage: 'en' })
}
},
}))
@@ -195,6 +200,104 @@ describe('journey-path-resolver', () => {
})
})
+ describe('resolveJourneyContext with Liquid track titles', () => {
+ afterEach(() => {
+ mockRenderContent.mockImplementation(async (content: string) => content)
+ })
+
+ const mockContext = {
+ currentProduct: 'github',
+ currentLanguage: 'en',
+ currentVersion: 'enterprise-cloud@latest',
+ }
+
+ const journeyPage = {
+ layout: 'journey-landing',
+ title: 'Enterprise onboarding',
+ permalink: '/enterprise-onboarding',
+ journeyTracks: [
+ {
+ id: 'getting_started',
+ title: 'Getting started with {% data variables.product.company_short %}',
+ guides: [
+ { href: '/enterprise-onboarding/setup' },
+ { href: '/enterprise-onboarding/deploy' },
+ ],
+ },
+ {
+ id: 'advanced',
+ title: 'Advanced {% data variables.product.company_short %} configuration',
+ guides: [{ href: '/enterprise-onboarding/advanced-setup' }],
+ },
+ ],
+ }
+
+ test('renders Liquid in trackTitle and nextTrackFirstGuide.trackTitle', async () => {
+ mockRenderContent.mockClear()
+ mockRenderContent.mockImplementation(async (content: string) =>
+ content.replaceAll('{% data variables.product.company_short %}', 'GitHub'),
+ )
+
+ const firstGuide = await resolveJourneyContext(
+ '/enterprise-onboarding/setup',
+ {},
+ mockContext,
+ journeyPage,
+ )
+ expect(firstGuide?.trackTitle).toBe('Getting started with GitHub')
+
+ const lastGuide = await resolveJourneyContext(
+ '/enterprise-onboarding/deploy',
+ {},
+ mockContext,
+ journeyPage,
+ )
+ expect(lastGuide?.trackTitle).toBe('Getting started with GitHub')
+ expect(lastGuide?.nextTrackFirstGuide?.trackTitle).toBe('Advanced GitHub configuration')
+
+ const titleCall = mockRenderContent.mock.calls.find(
+ ([content]) => content === journeyPage.journeyTracks[1].title,
+ )
+ expect(titleCall?.[2]).toEqual({ textOnly: true })
+ })
+
+ test('retries translated track titles with the English context', async () => {
+ mockRenderContent.mockImplementation(
+ async (content: string, context?: unknown, _options?: unknown) => {
+ void _options
+ if ((context as { currentLanguage?: string }).currentLanguage !== 'en') {
+ throw new Error('Translated data failed to render')
+ }
+ return content.replaceAll('{% data variables.product.company_short %}', 'GitHub')
+ },
+ )
+
+ const lastGuide = await resolveJourneyContext(
+ '/enterprise-onboarding/deploy',
+ {},
+ { ...mockContext, currentLanguage: 'ja' },
+ journeyPage,
+ )
+ expect(lastGuide?.trackTitle).toBe('Getting started with GitHub')
+ expect(lastGuide?.nextTrackFirstGuide?.trackTitle).toBe('Advanced GitHub configuration')
+ })
+
+ test('falls back to the raw track title when English rendering fails', async () => {
+ mockRenderContent.mockImplementation(async (content: string) => {
+ if (content.includes('{% data')) throw new Error('Data failed to render')
+ return content
+ })
+
+ const firstGuide = await resolveJourneyContext(
+ '/enterprise-onboarding/setup',
+ {},
+ mockContext,
+ journeyPage,
+ )
+ expect(firstGuide?.trackTitle).toBe(journeyPage.journeyTracks[0].title)
+ })
+ })
+
describe('resolveJourneyTracks', () => {
const mockContext = {
currentProduct: 'github',
diff --git a/src/landings/components/CategoryLanding.tsx b/src/landings/components/CategoryLanding.tsx
index 7b4909bee7cc..3d29b47b56f3 100644
--- a/src/landings/components/CategoryLanding.tsx
+++ b/src/landings/components/CategoryLanding.tsx
@@ -10,6 +10,7 @@ import { useCategoryLandingContext } from '@/frame/components/context/CategoryLa
import { ClientSideRedirects } from '@/rest/components/ClientSideRedirects'
import { RestRedirect } from '@/rest/components/RestRedirect'
import { ArticleCardItems } from '@/landings/types'
+import { filterCategoryItems } from '@/landings/lib/filter-category-items'
import { UtmPreserver } from '@/frame/components/UtmPreserver'
export const CategoryLanding = () => {
@@ -29,41 +30,12 @@ export const CategoryLanding = () => {
const [selectedComplexity, setSelectedComplexity] = useState('All')
const [selectedSurface, setSelectedSurface] = useState('All')
- const applyFilters = () => {
- let results = onlyFlatItems
-
- if (searchQuery) {
- results = results.filter((token) => {
- return Object.values(token).some((value) => {
- if (typeof value === 'string') {
- return value.toLowerCase().includes(searchQuery.toLowerCase())
- } else if (Array.isArray(value)) {
- return value.some(
- (item) =>
- typeof item === 'string' && item.toLowerCase().includes(searchQuery.toLowerCase()),
- )
- }
- return false
- })
- })
- }
-
- if (selectedCategory !== 'All') {
- results = results.filter((item) => item.category?.includes(selectedCategory))
- }
-
- if (selectedComplexity !== 'All') {
- results = results.filter((item) => item.complexity?.includes(selectedComplexity))
- }
-
- if (selectedSurface !== 'All') {
- results = results.filter((item) => item.surface?.includes(selectedSurface))
- }
-
- return results
- }
-
- const searchResults = applyFilters()
+ const searchResults = filterCategoryItems(onlyFlatItems, {
+ query: searchQuery,
+ category: selectedCategory,
+ complexity: selectedComplexity,
+ surface: selectedSurface,
+ })
const handleSearch = (query: string) => {
setSearchQuery(query)
diff --git a/src/landings/components/shared/LandingArticleGridWithFilter.tsx b/src/landings/components/shared/LandingArticleGridWithFilter.tsx
index 999dfda29088..fcc615aa01ce 100644
--- a/src/landings/components/shared/LandingArticleGridWithFilter.tsx
+++ b/src/landings/components/shared/LandingArticleGridWithFilter.tsx
@@ -61,6 +61,7 @@ export const ArticleGrid = ({
updateParams,
}: ArticleGridProps) => {
const { t } = useTranslation('product_landing')
+ const { locale } = useRouter()
const articlesPerPage = useResponsiveArticlesPerPage()
const inputRef = useRef(null)
@@ -71,7 +72,7 @@ export const ArticleGrid = ({
const selectedCategory = params['articles-category'] || ALL_CATEGORIES
const currentPage = parseInt(params['articles-page'] || '1', 10)
- const allArticles = useMemo(() => flattenArticles(tocItems), [tocItems])
+ const allArticles = useMemo(() => flattenArticles(tocItems, locale), [tocItems, locale])
const stopWords = useMemo(() => deriveStopWords(allArticles), [allArticles])
@@ -102,9 +103,9 @@ export const ArticleGrid = ({
const lowerCategory = category.toLowerCase()
return includedCategories.some((included) => included.toLowerCase() === lowerCategory)
})
- .sort((a, b) => a.localeCompare(b)),
+ .sort((a, b) => a.localeCompare(b, locale)),
],
- [filteredArticlesByLandingType, includedCategories],
+ [filteredArticlesByLandingType, includedCategories, locale],
)
const selectedCategoryIndex = useMemo(() => {
@@ -141,7 +142,12 @@ export const ArticleGrid = ({
const filteredResults = applyFilters()
const totalPages = Math.ceil(filteredResults.length / articlesPerPage)
- const startIndex = (currentPage - 1) * articlesPerPage
+ // Page count depends on viewport width and filters, so a URL page can be out of range here.
+ const displayPage = Math.min(
+ Math.max(1, Number.isFinite(currentPage) ? currentPage : 1),
+ Math.max(1, totalPages),
+ )
+ const startIndex = (displayPage - 1) * articlesPerPage
const paginatedResults = filteredResults.slice(startIndex, startIndex + articlesPerPage)
const handleSearch = (query: string) => {
@@ -347,7 +353,7 @@ export const ArticleGrid = ({
{
+ // Safari button clicks and window switches blur with a null relatedTarget; keep it open.
+ const next = e.relatedTarget as Node | null
+ if (open && next && !e.currentTarget.contains(next)) setOpen(false)
+ }}
+ >
)
}
-function renderItem(kind: SchemaKindKey, item: AnySchemaItem, allObjects: ObjectT[]): JSX.Element {
+function renderItem(
+ kind: SchemaKindKey,
+ item: AnySchemaItem,
+ implementers: InterfaceImplementerT[],
+): JSX.Element {
const id = (item as { id?: string }).id ?? item.name
const key = `${kind}-${id}`
switch (kind) {
@@ -97,7 +101,7 @@ function renderItem(kind: SchemaKindKey, item: AnySchemaItem, allObjects: Object
Represents true or false values.
Represents signed double-precision fractional values as specified by IEEE 754.
", "id": "float", - "href": "/graphql/reference/other#other-scalar-float", + "href": "/graphql/reference/other#scalar-float", "category": "other" }, { @@ -170,14 +170,14 @@ "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"VXNlci0xMA==\") or integer (such as 4) input value will be accepted as an ID.
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
", "id": "int", - "href": "/graphql/reference/other#other-scalar-int", + "href": "/graphql/reference/other#scalar-int", "category": "other" }, { @@ -191,7 +191,7 @@ "name": "String", "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
", "id": "string", - "href": "/graphql/reference/other#other-scalar-string", + "href": "/graphql/reference/other#scalar-string", "category": "other" }, { diff --git a/src/graphql/data/ghes-3.18/schema-other.json b/src/graphql/data/ghes-3.18/schema-other.json index 0ed061286f70..7bcfef438a88 100644 --- a/src/graphql/data/ghes-3.18/schema-other.json +++ b/src/graphql/data/ghes-3.18/schema-other.json @@ -1622,7 +1622,7 @@ "name": "Boolean", "description": "Represents true or false values.
Represents signed double-precision fractional values as specified by IEEE 754.
", "id": "float", - "href": "/graphql/reference/other#other-other-other-other-other-other-scalar-float", + "href": "/graphql/reference/other#scalar-float", "category": "other" }, { @@ -1685,14 +1685,14 @@ "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"VXNlci0xMA==\") or integer (such as 4) input value will be accepted as an ID.
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
", "id": "int", - "href": "/graphql/reference/other#other-other-other-other-other-other-scalar-int", + "href": "/graphql/reference/other#scalar-int", "category": "other" }, { @@ -1706,7 +1706,7 @@ "name": "String", "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
", "id": "string", - "href": "/graphql/reference/other#other-other-other-other-other-other-scalar-string", + "href": "/graphql/reference/other#scalar-string", "category": "other" }, { diff --git a/src/graphql/data/ghes-3.19/schema-other.json b/src/graphql/data/ghes-3.19/schema-other.json index 2079a4d94ee8..0bfd0ed98845 100644 --- a/src/graphql/data/ghes-3.19/schema-other.json +++ b/src/graphql/data/ghes-3.19/schema-other.json @@ -1601,7 +1601,7 @@ "name": "Boolean", "description": "Represents true or false values.
Represents signed double-precision fractional values as specified by IEEE 754.
", "id": "float", - "href": "/graphql/reference/other#other-other-other-other-other-scalar-float", + "href": "/graphql/reference/other#scalar-float", "category": "other" }, { @@ -1664,14 +1664,14 @@ "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"VXNlci0xMA==\") or integer (such as 4) input value will be accepted as an ID.
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
", "id": "int", - "href": "/graphql/reference/other#other-other-other-other-other-scalar-int", + "href": "/graphql/reference/other#scalar-int", "category": "other" }, { @@ -1685,7 +1685,7 @@ "name": "String", "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
", "id": "string", - "href": "/graphql/reference/other#other-other-other-other-other-scalar-string", + "href": "/graphql/reference/other#scalar-string", "category": "other" }, { diff --git a/src/graphql/data/ghes-3.20/schema-other.json b/src/graphql/data/ghes-3.20/schema-other.json index 9f292395e7fa..036e36567fb1 100644 --- a/src/graphql/data/ghes-3.20/schema-other.json +++ b/src/graphql/data/ghes-3.20/schema-other.json @@ -1601,7 +1601,7 @@ "name": "Boolean", "description": "Represents true or false values.
Represents signed double-precision fractional values as specified by IEEE 754.
", "id": "float", - "href": "/graphql/reference/other#other-other-other-other-scalar-float", + "href": "/graphql/reference/other#scalar-float", "category": "other" }, { @@ -1671,14 +1671,14 @@ "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"VXNlci0xMA==\") or integer (such as 4) input value will be accepted as an ID.
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
", "id": "int", - "href": "/graphql/reference/other#other-other-other-other-scalar-int", + "href": "/graphql/reference/other#scalar-int", "category": "other" }, { @@ -1692,7 +1692,7 @@ "name": "String", "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
", "id": "string", - "href": "/graphql/reference/other#other-other-other-other-scalar-string", + "href": "/graphql/reference/other#scalar-string", "category": "other" }, { diff --git a/src/graphql/data/ghes-3.21/schema-other.json b/src/graphql/data/ghes-3.21/schema-other.json index c256d3c711c8..4e0f78604328 100644 --- a/src/graphql/data/ghes-3.21/schema-other.json +++ b/src/graphql/data/ghes-3.21/schema-other.json @@ -164,7 +164,7 @@ "name": "Boolean", "description": "Represents true or false values.
Represents signed double-precision fractional values as specified by IEEE 754.
", "id": "float", - "href": "/graphql/reference/other#other-other-other-scalar-float", + "href": "/graphql/reference/other#scalar-float", "category": "other" }, { @@ -234,14 +234,14 @@ "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"VXNlci0xMA==\") or integer (such as 4) input value will be accepted as an ID.
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
", "id": "int", - "href": "/graphql/reference/other#other-other-other-scalar-int", + "href": "/graphql/reference/other#scalar-int", "category": "other" }, { @@ -255,7 +255,7 @@ "name": "String", "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
", "id": "string", - "href": "/graphql/reference/other#other-other-other-scalar-string", + "href": "/graphql/reference/other#scalar-string", "category": "other" }, { diff --git a/src/graphql/data/ghes-3.22/schema-other.json b/src/graphql/data/ghes-3.22/schema-other.json index 61e4e1512507..e0420f2f3c8c 100644 --- a/src/graphql/data/ghes-3.22/schema-other.json +++ b/src/graphql/data/ghes-3.22/schema-other.json @@ -77,7 +77,7 @@ "name": "Boolean", "description": "Represents true or false values.
Represents signed double-precision fractional values as specified by IEEE 754.
", "id": "float", - "href": "/graphql/reference/other#other-other-scalar-float", + "href": "/graphql/reference/other#scalar-float", "category": "other" }, { @@ -147,14 +147,14 @@ "name": "ID", "description": "Represents a unique identifier that is Base64 obfuscated. It is often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as \"VXNlci0xMA==\") or integer (such as 4) input value will be accepted as an ID.
Represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.
", "id": "int", - "href": "/graphql/reference/other#other-other-scalar-int", + "href": "/graphql/reference/other#scalar-int", "category": "other" }, { @@ -168,7 +168,7 @@ "name": "String", "description": "Represents textual data as UTF-8 character sequences. This type is most often used by GraphQL to represent free-form human-readable text.
", "id": "string", - "href": "/graphql/reference/other#other-other-scalar-string", + "href": "/graphql/reference/other#scalar-string", "category": "other" }, { diff --git a/src/graphql/lib/categories.ts b/src/graphql/lib/categories.ts index 76eb35cd02c9..cf89598a83bb 100644 --- a/src/graphql/lib/categories.ts +++ b/src/graphql/lib/categories.ts @@ -177,3 +177,8 @@ export function categoryTitle(slug: string): string { return slug.charAt(0).toUpperCase() + slug.slice(1) } } + +// Server and browser must share one collation, or hydration sees a different item order. +export function compareByName(a: { name: string }, b: { name: string }): number { + return a.name.toLowerCase().localeCompare(b.name.toLowerCase(), 'en') +} diff --git a/src/graphql/lib/index.ts b/src/graphql/lib/index.ts index 8f0cfd8a8da2..03e793f5360e 100644 --- a/src/graphql/lib/index.ts +++ b/src/graphql/lib/index.ts @@ -7,6 +7,8 @@ import languages from '@/languages/lib/languages-server' import { allVersions } from '@/versions/lib/all-versions' import type { GraphqlT, + InterfaceImplementerT, + ObjectT, PreviewT, ChangelogItemT, BreakingChangesT, @@ -73,6 +75,26 @@ export function getAllGraphqlObjects(version: string): GraphqlT[] { return allObjectsByVersion.get(graphqlVersion)! } +// Category pages serialize props to the client, so keep only what Interface renders. +export function getGraphqlInterfaceImplementers( + version: string, + interfaceNames: string[], +): InterfaceImplementerT[] { + if (interfaceNames.length === 0) return [] + const names = new Set(interfaceNames) + const implementers: InterfaceImplementerT[] = [] + for (const object of getAllGraphqlObjects(version) as ObjectT[]) { + const matching = (object.implements ?? []).filter((item) => names.has(item.name)) + if (matching.length === 0) continue + implementers.push({ + name: object.name, + href: object.href, + implements: matching.map((item) => ({ name: item.name })), + }) + } + return implementers +} + export function getKindOrder(): SchemaKindKey[] { return ALL_KIND_KEYS } diff --git a/src/graphql/pages/reference.tsx b/src/graphql/pages/reference.tsx index 77dba5be2983..f728a419dd48 100644 --- a/src/graphql/pages/reference.tsx +++ b/src/graphql/pages/reference.tsx @@ -8,7 +8,7 @@ import { getMainContext, addUINamespaces, } from '@/frame/components/context/MainContext' -import type { ObjectT } from '@/graphql/components/types' +import type { InterfaceImplementerT } from '@/graphql/components/types' import type { ExtendedRequest } from '@/types/types' import { AutomatedPage } from '@/automated-pipelines/components/AutomatedPage' import { @@ -21,6 +21,7 @@ import { KIND_SLUG_PREFIX, KIND_LABELS_PLURAL, KIND_URL_SEGMENT, + compareByName, isValidCategory, } from '@/graphql/lib/categories' @@ -28,7 +29,7 @@ type Props = { mainContext: MainContextT automatedPageContext: AutomatedPageContextT schema: CategorySchema - allObjects: ObjectT[] + implementers: InterfaceImplementerT[] language: string categorySlug: string } @@ -37,11 +38,13 @@ export default function GraphqlReferencePage({ mainContext, automatedPageContext, schema, - allObjects, + implementers, categorySlug, }: Props) { // Keying by categorySlug prevents navigation from reusing stale dangerouslySetInnerHTML content. - const content =deployed event')
+ })
+
+ test('converts every quoted word in a description', async () => {
+ const rendered = await helpers.getDescription(
+ "Choose 'custom' or 'system' here. Defaults to 'custom' if not specified",
+ )
+
+ expect(rendered).toContain('Choose custom or system here')
+ expect(rendered).toContain('Defaults to custom if')
+ })
+})
diff --git a/src/graphql/tests/get-schema-files.ts b/src/graphql/tests/get-schema-files.ts
index a8b5b7602abe..e8e9c6e65259 100644
--- a/src/graphql/tests/get-schema-files.ts
+++ b/src/graphql/tests/get-schema-files.ts
@@ -9,7 +9,10 @@ import {
getGraphqlChangelog,
getGraphqlBreakingChanges,
getPreviews,
+ getAllGraphqlObjects,
+ getGraphqlInterfaceImplementers,
} from '../lib/index'
+import type { ObjectT } from '@/graphql/components/types'
interface GraphqlType {
kind: string
@@ -59,4 +62,32 @@ describe('graphql schema', () => {
expect(schema).toBeDefined()
}
})
+
+ test('getGraphqlInterfaceImplementers returns nothing without interface names', () => {
+ expect(getGraphqlInterfaceImplementers('free-pro-team@latest', [])).toEqual([])
+ })
+
+ test('getGraphqlInterfaceImplementers returns slim implementers for a category', () => {
+ const version = 'free-pro-team@latest'
+ const schema = getGraphqlSchema(version, 'issues') as { interfaces?: { name: string }[] }
+ const interfaceNames = (schema.interfaces ?? []).map((item) => item.name)
+ expect(interfaceNames.length).toBeGreaterThan(0)
+
+ const implementers = getGraphqlInterfaceImplementers(version, interfaceNames)
+ const expected = (getAllGraphqlObjects(version) as ObjectT[]).filter((object) =>
+ object.implements?.some((implementsItem) => interfaceNames.includes(implementsItem.name)),
+ )
+ expect(implementers.length).toBeGreaterThan(0)
+ expect(implementers.map((object) => object.name)).toEqual(expected.map((object) => object.name))
+ for (const implementer of implementers) {
+ expect(Object.keys(implementer).sort()).toEqual(['href', 'implements', 'name'])
+ for (const implementsItem of implementer.implements ?? []) {
+ expect(Object.keys(implementsItem)).toEqual(['name'])
+ expect(interfaceNames).toContain(implementsItem.name)
+ }
+ }
+ expect(JSON.stringify(implementers).length).toBeLessThan(
+ JSON.stringify(getAllGraphqlObjects(version)).length / 10,
+ )
+ })
})
diff --git a/src/journeys/lib/journey-path-resolver.ts b/src/journeys/lib/journey-path-resolver.ts
index ecb1640357a3..7b6f0446e2ea 100644
--- a/src/journeys/lib/journey-path-resolver.ts
+++ b/src/journeys/lib/journey-path-resolver.ts
@@ -69,6 +69,20 @@ function needsRendering(str: string): boolean {
return str.includes('{{') || str.includes('{%') || str.includes('[') || str.includes('<')
}
+async function renderTextField(value: string, context: Context): Promise/)
expect(result).not.toMatch(/<\/p>$/)
})
+ test('renders fpt version conditionals as free-pro-team', async () => {
+ expect(await renderLiquid('{% ifversion fpt %}A{% else %}B{% endif %}')).toBe('A')
+ expect(await renderLiquid('{% ifversion fpt or ghec %}A{% else %}B{% endif %}')).toBe('A')
+ expect(await renderLiquid('{% ifversion not fpt %}A{% else %}B{% endif %}')).toBe('B')
+ })
+ test('renders feature flags enabled on free-pro-team', async () => {
+ expect(await renderLiquid('{% ifversion code-search-upgrade %}A{% else %}B{% endif %}')).toBe(
+ 'A',
+ )
+ })
})
describe('getPageTitle', () => {
@@ -149,6 +161,21 @@ describe('loadConfig', () => {
const cfg = loadConfig('data/llms-txt/config-monolith.yml')
expect(cfg.title).toBe('GitHub')
})
+
+ test('every pinned page exists in content', () => {
+ for (const configPath of [
+ 'data/llms-txt/config-docs.yml',
+ 'data/llms-txt/config-monolith.yml',
+ ]) {
+ const missing = loadConfig(configPath).pinned_pages.filter(
+ (p) => !fs.existsSync(`content/${p}.md`) && !fs.existsSync(`content/${p}/index.md`),
+ )
+ expect(
+ missing,
+ `Pinned pages in ${configPath} not found. If you moved or renamed these pages, update pinned_pages in data/llms-txt/config-default.yml.`,
+ ).toEqual([])
+ }
+ })
})
describe('generate', () => {
@@ -222,6 +249,20 @@ describe('generate', () => {
expect(out).toMatch(/\[REST API\]/)
})
+ test('warns about pinned pages that do not exist and keeps the rest', async () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ try {
+ const pages = makePages({ rest: { title: 'REST API' } })
+ const out = await generate(pages, {}, { ...baseConfig, pinned_pages: ['rest', 'gone/page'] })
+ expect(out).toMatch(/\[REST API\]/)
+ expect(out).not.toMatch(/gone\/page/)
+ expect(warn).toHaveBeenCalledTimes(1)
+ expect(warn.mock.calls[0][0]).toMatch(/^::warning::.*skipped: gone\/page\./)
+ } finally {
+ warn.mockRestore()
+ }
+ })
+
test('includes title, description, how_to_use, and auto_update_comment', async () => {
const out = await generate(
{},
diff --git a/src/workflows/tests/git-utils.ts b/src/workflows/tests/git-utils.ts
new file mode 100644
index 000000000000..9533e3f971c2
--- /dev/null
+++ b/src/workflows/tests/git-utils.ts
@@ -0,0 +1,95 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+const searchCode = vi.fn()
+vi.mock('@/workflows/github', async (importOriginal) => {
+ const actual = await importOriginal