docs: consolidate VS Code and GitHub Copilot plugin docs - #2889
docs: consolidate VS Code and GitHub Copilot plugin docs#2889marcel-rbro wants to merge 9 commits into
Conversation
The VS Code marketplace install and the Copilot CLI/desktop app pages document the same plugin, so present all three as one family: - Copilot hub lists VS Code as a third surface and links to it - VS Code page points at the hub and both sibling clients instead of the deleted install-from-source flow - CLI and desktop app pages cross-link back to VS Code - By provider entry names all three clients
marcel-rbro
added
documentation
|
✅ Preview for this PR (commit |
Both existing provider hubs use the "What you can build" heading, so match it. Also name VS Code in the GitHub Copilot card on the integrations landing page, since the hub it links to now covers it.
- Drop the stale preview-feature caveat from the VS Code page; VS Code's agent plugins docs no longer mark the feature as preview, and the CLI and desktop app pages already omit it - Add Authentication paths to the VS Code and desktop app pages so the CLI and SDK skills document their token setup, matching the CLI page - Restore both default marketplaces in the chat.plugins.marketplaces snippet; the previous one silently dropped github/copilot-plugins - Use <kbd> for keyboard shortcuts, matching mcp.md and console.md - Format the apify plugin and agent names as code in headings - Split the desktop app install step to match its numbered callouts - Explain on the CLI page why it needs the marketplace added manually - Switch the settings snippet to json5, the repo's convention for JSON with comments
Per review feedback: VS Code is its own platform, not something under GitHub Copilot. Drop it from the by-provider line and the Copilot card on the integrations landing page, and reword the hub intro so VS Code reads as a separate platform that runs the same plugin. The VS Code card stays on the hub as a cross-reference.
Audit the screenshots against CONTRIBUTING.md - keep only what prose can't convey, and recolour the surviving indicators to #F86606. - Remove 10 screenshots that restated their own steps or showed commands already given in copyable code blocks; move the few details they carried into prose - Recolour the indicators on the 5 remaining images from brick red to the #F86606 required by CONTRIBUTING.md - Merge three stacked admonitions on the CLI page into one, moving the read-only and slow-connection notes into the steps they belong to - Use <kbd> for the CLI key references - Expand Visual Studio Code (VS Code) on first mention per page - Order the hub cards CLI, desktop app, VS Code - Fix the CLI authorization alt text, which described a browser window while showing a terminal
TC-MO
left a comment
TC-MO
left a comment
There was a problem hiding this comment.
Good split, pages read well. One blocker: the CLI install steps assume the
Copilot CLI can't see the plugin by default, but awesome-copilot ships
registered and the plugin is in it. Please retest /plugin install apify@awesome-copilot on a clean profile.
Before merge I'd also like the triplicated skills/prompts/limitations blocks
pulled into a partial (they're already drifting), and one story on whether VS
Code is a Copilot client. Rest is inline.
|
|
||
| ## Install the plugin and sign in | ||
|
|
||
| The plugin lives in an Apify marketplace that you add to Copilot with a repository URL. The CLI doesn't register that marketplace by default, so add it before you install - unlike [Visual Studio Code (VS Code)](/integrations/vscode) and the [desktop app](/integrations/github-copilot-desktop), which find the plugin in a marketplace they already know about. Installing the plugin also sets up the bundled Apify MCP server and signs you in, so there's no separate authentication step. Read-only tools like searching Apify Store and fetching Actor details work without signing in, but you need to authenticate to run Actors and access your account data. |
There was a problem hiding this comment.
why an here? Shouldn't it be the? Especially since 2 lines below you use the. Besides that isn't that just plain wrong? Apify is part of awesome-copilot which ships by default 🤔
There was a problem hiding this comment.
Yep, since awesome-copilot submission this is outdated - cc @daveomri
| /plugin install apify@apify | ||
| ``` | ||
|
|
||
| This installs the plugin, its five [bundled skills](#bundled-skills), and the bundled Apify MCP server (`https://mcp.apify.com/`). Copilot usually opens a browser tab for the Apify sign-in automatically once the install finishes. |
There was a problem hiding this comment.
What happens unusually? (LOC 53 does but why is it so far away 🤷 )
|
|
||
|  | ||
|
|
||
| On the first start, Copilot may report that `apify-mcp-server` is taking longer than expected to connect, then that it gave up waiting. The server usually finishes connecting a moment later and logs `MCP server 'apify-mcp-server' connected`, so no action is needed. |
There was a problem hiding this comment.
what happens unusually? Not only that but just... we are describing a possible bug like it is part of the procedure. That feels just plain wrong.
If no action is needed why mention it? Either drop it or separate section I would say would be better.
|
|
||
| The plugin lives in an Apify marketplace that you add to Copilot with a repository URL. The CLI doesn't register that marketplace by default, so add it before you install - unlike [Visual Studio Code (VS Code)](/integrations/vscode) and the [desktop app](/integrations/github-copilot-desktop), which find the plugin in a marketplace they already know about. Installing the plugin also sets up the bundled Apify MCP server and signs you in, so there's no separate authentication step. Read-only tools like searching Apify Store and fetching Actor details work without signing in, but you need to authenticate to run Actors and access your account data. | ||
|
|
||
| 1. In a Copilot session, add the Apify marketplace: |
There was a problem hiding this comment.
Is there a way to install plugin not in a copilot session?
There was a problem hiding this comment.
Yes, GH Copilot can read globally installed plugins, plugins in that folder, enterprise managed Copilot can install some plugins by default. Here it is better to be accurate, but I agree it looks odd.
| ## Limitations | ||
|
|
||
| - Long-running Actors may exceed the time a single tool call waits for completion. Reduce the scope or split the work across multiple prompts. | ||
| - Each Actor run consumes Apify platform usage from your plan in addition to any VS Code usage. See [Billing](/account/billing) for details. | ||
| - Skills that edit files in your project (Actor development, actorization, SDK integration) make local changes - review them before deploying or committing. |
There was a problem hiding this comment.
Are those deliberately different than the ones in cli doc LOC 145 & desktop doc LOC 131?
If yes where did the drift come from? If not why not a partial?
| <Card | ||
| title="VS Code" | ||
| desc="Install the Apify plugin from the VS Code plugin marketplace to discover, run, and build Actors in your editor." | ||
| to="/integrations/vscode" | ||
| imageUrl="/img/platform/integrations/vscode.svg" | ||
| imageUrlDarkTheme="/img/platform/integrations/vscode-white.svg" | ||
| smallImage | ||
| /> |
There was a problem hiding this comment.
per 3a85911 you wanted to stop presenting VSCode as off shoot of copilot, yet leave it in copilot index file?
There was a problem hiding this comment.
2 cents, not my call but from audience perspective I think this makes sense - user can reason about GC in VS Code in two ways:
1 . "I have Copilot and want to use it in VS Code" - clicks GitHub Copilot card, finds VS Code here
2. "I have VS Code and I want to use some AI int" - finds VS Code on top level.
VS Code/ GitHub Copilot distinction is kinda messy so this reflects the reality :|
| - An `apify` routing agent that picks the right tool or skill from a natural-language request. | ||
| - Five built-in skills for common workflows (see [Bundled skills](#bundled-skills) below). | ||
|
|
||
| This guide covers installation from the plugin marketplace in VS Code. It's the same plugin that powers the [GitHub Copilot CLI](/integrations/github-copilot-cli) and the [GitHub Copilot desktop app](/integrations/github-copilot-desktop) - install it once per client you use. |
There was a problem hiding this comment.
Sorry, can you expand please - I don't think I understand the issue here.
VS Code docs says the VS Code can see Agent Plugins installed by GC CLI which is true.
All of the VSC, GC Desktop and GC CLI are powered by the same source (Apify plugin listed in awesome-copilot) I don't see how docs are wrong here.
There was a problem hiding this comment.
Of course! My issue was with the ending install it once per client you use to me it suggests that if I use more than one of those I should install it separately per the client, but that is not the case right? It should be installed once and each client will pick it up?
There was a problem hiding this comment.
Got it, I think we should just remove the ending - availability generally depends on a lot of things (versions of VSC and GHC) and it might be tricky to figure out correct setup. Also domain is moving very fast so I would be careful here.
|
|
||
| Describe what you want in plain language. | ||
|
|
||
| > Use Apify to find a good Actor for scraping Google Maps places. Show me the best option, its input requirements, pricing model, and what kind of dataset output it returns. Do not run the Actor yet. |
There was a problem hiding this comment.
Is blockquote the best here? They are rendered in similar style to admonitions so I am not a fan. I would use ```text for prompts. And that goes for all blockqutoes in the doc
There was a problem hiding this comment.
Is there some convention we can all follow? I am fine with rewriting in once but rewriting it every 2 months seems not very productive.
There was a problem hiding this comment.
Hmm those might be remnants of older style, I'll double check our standards & style-guide files if its not codified properly we will codify it and we can rewrite later.
| _Ultimate scraper:_ | ||
|
|
||
| > Find 10 highly rated coffee shops in Seattle with name, address, rating, phone, and website. | ||
|
|
||
| _Actor development:_ | ||
|
|
||
| > Create an Apify Actor that accepts a `startUrl` and `maxPages` input, crawls the site, and stores each page title and URL. | ||
|
|
||
| _SDK integration:_ | ||
|
|
||
| > Add Apify to this project. The Node.js API route should run an Actor and return dataset items as JSON. |
There was a problem hiding this comment.
The cursive is a heading without being a heading. Not sure, maybe a table would be better here? Or some other construction but as it stands it looks bad.
|
I tried to address some of the issues as this PR is becoming stale and it is blocking other activities. @daveomri can you please look at the GitHub related issues? |
| The plugin lives in an Apify marketplace that you add to Copilot with a repository URL. The CLI doesn't register that marketplace by default, so add it before you install - unlike [Visual Studio Code (VS Code)](/integrations/vscode) and the [desktop app](/integrations/github-copilot-desktop), which find the plugin in a marketplace they already know about. Installing the plugin also sets up the bundled Apify MCP server and signs you in, so there's no separate authentication step. Read-only tools like searching Apify Store and fetching Actor details work without signing in, but you need to authenticate to run Actors and access your account data. | ||
|
|
||
| 1. In a Copilot session, add the Apify marketplace: | ||
|
|
||
| ```text | ||
| /plugin marketplace add https://github.com/apify/apify-github-copilot-plugin | ||
| ``` | ||
|
|
||
| Copilot confirms with `Marketplace "apify" added successfully`. | ||
|
|
||
| 1. Install the `apify` plugin from the marketplace: | ||
|
|
||
| ```text | ||
| /plugin install apify@apify | ||
| ``` | ||
|
|
There was a problem hiding this comment.
| The plugin lives in an Apify marketplace that you add to Copilot with a repository URL. The CLI doesn't register that marketplace by default, so add it before you install - unlike [Visual Studio Code (VS Code)](/integrations/vscode) and the [desktop app](/integrations/github-copilot-desktop), which find the plugin in a marketplace they already know about. Installing the plugin also sets up the bundled Apify MCP server and signs you in, so there's no separate authentication step. Read-only tools like searching Apify Store and fetching Actor details work without signing in, but you need to authenticate to run Actors and access your account data. | |
| 1. In a Copilot session, add the Apify marketplace: | |
| ```text | |
| /plugin marketplace add https://github.com/apify/apify-github-copilot-plugin | |
| ``` | |
| Copilot confirms with `Marketplace "apify" added successfully`. | |
| 1. Install the `apify` plugin from the marketplace: | |
| ```text | |
| /plugin install apify@apify | |
| ``` | |
| The plugin is published in the `awesome-copilot` marketplace, which the GitHub Copilot CLI registers by default - the same marketplace [Visual Studio Code (VS Code)](/integrations/vscode) and the [desktop app](/integrations/github-copilot-desktop) use - so you can install it without adding a marketplace first. Installing the plugin also sets up the bundled Apify MCP server and signs you in, so there's no separate authentication step. Read-only tools like searching Apify Store and fetching Actor details work without signing in, but you need to authenticate to run Actors and access your account data. | |
| 1. Install the `apify` plugin from the `awesome-copilot` marketplace: | |
| ```text | |
| /plugin install apify@awesome-copilot | |
| ``` |
|
|
||
| ### The `apify` plugin isn't installed | ||
|
|
||
| Run `/plugin marketplace add https://github.com/apify/apify-github-copilot-plugin` to add the marketplace, then `/plugin install apify@apify` to install the plugin. Confirm the marketplace was added with `/plugin marketplace browse apify`. |
There was a problem hiding this comment.
| Run `/plugin marketplace add https://github.com/apify/apify-github-copilot-plugin` to add the marketplace, then `/plugin install apify@apify` to install the plugin. Confirm the marketplace was added with `/plugin marketplace browse apify`. | |
| Run `/plugin install apify@awesome-copilot` to install the plugin from the `awesome-copilot` marketplace, which the CLI registers by default. Browse the marketplace with `/plugin marketplace browse awesome-copilot` to confirm the `apify` plugin is listed. |
| /plugin install apify@apify | ||
| ``` | ||
|
|
||
| This installs the plugin, its five [bundled skills](#bundled-skills), and the bundled Apify MCP server (`https://mcp.apify.com/`). Copilot usually opens a browser tab for the Apify sign-in automatically once the install finishes. |
There was a problem hiding this comment.
| This installs the plugin, its five [bundled skills](#bundled-skills), and the bundled Apify MCP server (`https://mcp.apify.com/`). Copilot usually opens a browser tab for the Apify sign-in automatically once the install finishes. | |
| This installs the plugin, its five [bundled skills](#bundled-skills), and the bundled Apify MCP server (`https://mcp.apify.com/`). Copilot then opens a browser tab for the Apify sign-in. |
| On the first start, Copilot may report that `apify-mcp-server` is taking longer than expected to connect, then that it gave up waiting. The server usually finishes connecting a moment later and logs `MCP server 'apify-mcp-server' connected`, so no action is needed. | ||
|
|
||
| If no browser tab opens, or the server never connects, connect it yourself with the [manual steps](#connect-the-mcp-server-manually) below. |
There was a problem hiding this comment.
| On the first start, Copilot may report that `apify-mcp-server` is taking longer than expected to connect, then that it gave up waiting. The server usually finishes connecting a moment later and logs `MCP server 'apify-mcp-server' connected`, so no action is needed. | |
| If no browser tab opens, or the server never connects, connect it yourself with the [manual steps](#connect-the-mcp-server-manually) below. | |
| If no browser tab opens, or `apify-mcp-server` doesn't connect, use the [manual steps](#connect-the-mcp-server-manually) below. |
| ### The Apify MCP server won't authenticate | ||
|
|
||
| Installation normally signs you in automatically. If the browser prompt didn't appear or you skipped it, connect the server manually: run `/mcp`, select `apify-mcp-server`, and choose to authenticate, as described in [Connect the MCP server manually](#connect-the-mcp-server-manually). Read-only tools work without signing in, so run a search prompt first to confirm the server is connected. | ||
|
|
There was a problem hiding this comment.
| ### The server is slow to connect on first start | |
| On the first start, Copilot may report that `apify-mcp-server` is taking longer than expected to connect, then that it gave up waiting. The server usually finishes connecting a moment later and logs `MCP server 'apify-mcp-server' connected`. If it doesn't, connect it with the [manual steps](#connect-the-mcp-server-manually). | |
5 participants
Combines #2871 (VS Code) and #2874 (GitHub Copilot CLI and desktop app) into one change. All three clients run the same Apify plugin, so they need to ship together and cross-link to each other - merging either PR alone leaves the docs either duplicated or with a coverage hole.
Commits from both original PRs are preserved; the final commit wires the VS Code page into the GitHub Copilot hub.
Supersedes #2871 and #2874.