diff --git a/docs/real-world-development/app/0-prerequisites.md b/docs/real-world-development/app/0-prerequisites.md index ec57d389..1a7e2513 100644 --- a/docs/real-world-development/app/0-prerequisites.md +++ b/docs/real-world-development/app/0-prerequisites.md @@ -3,7 +3,7 @@ title: "Lesson 0 - Prerequisites" description: "Set up for the GitHub Copilot app lessons: install Node.js for the Tailspin Toys project and create your own copy of the repository from the template." authors: - geektrainer -lastUpdated: 2026-06-30 +lastUpdated: 2026-10-22 --- The GitHub Copilot app is a desktop app serving as your central hub for both Copilot and GitHub. It provides quick access to issues and pull requests, and of course allows you to build using GitHub Copilot. During this workshop you'll be working locally, updating the Tailspin Toys app, built on Astro, using the GitHub Copilot app. Before you get started, let's ensure Node.js is installed locally, then install the Copilot app. @@ -24,9 +24,10 @@ The simplest option on every platform is the official installer: ```shell node --version + npm --version ``` -3. If it meets the requirements in the project's README and `package.json`, you can skip to the next section. +3. If both commands succeed and Node.js meets the requirements in the project's README and `package.json`, you can skip to the next section. > [!TIP] > You only need to complete these steps if you don't have Node installed, or you need to update. @@ -39,9 +40,13 @@ The simplest option on every platform is the official installer: ```bash node --version + npm --version ``` -9. You should see the version you installed. +9. You should see the installed Node.js and npm versions. + +> [!IMPORTANT] +> The Copilot app's agent must also be able to run `node --version` and `npm --version`. Success in your usual terminal does not guarantee they are available to the app. Fully quit and reopen the app after installing Node.js or changing PATH. If either command still fails in a session, follow the [session environment troubleshooting steps][session-environment] before continuing. > [!IMPORTANT] > Each worktree also needs the project dependencies and Playwright Chromium for E2E checks. Follow the Tailspin Toys repository's README when preparing a worktree, and review any installation request before approving it. @@ -86,3 +91,4 @@ Next, you'll [install the GitHub Copilot app][next-lesson], connect the reposito [node-download]: https://nodejs.org/en/download [template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository [about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[session-environment]: ../3-agent-modes/#start-a-session-from-the-issue diff --git a/docs/real-world-development/app/1-install-copilot-app.md b/docs/real-world-development/app/1-install-copilot-app.md index 368feeec..4db27840 100644 --- a/docs/real-world-development/app/1-install-copilot-app.md +++ b/docs/real-world-development/app/1-install-copilot-app.md @@ -3,7 +3,7 @@ title: "Lesson 1 - Installing the GitHub Copilot app" description: "Install the GitHub Copilot app, connect the repository you created from the template, get oriented in the workspace, and try a quick chat." authors: - geektrainer -lastUpdated: 2026-10-05 +lastUpdated: 2026-10-22 --- The **[GitHub Copilot app][about-copilot-app]** is a desktop application for agent-driven development. It is built on GitHub Copilot CLI and integrates natively with GitHub, so your repositories, branches, and CI pipelines work out of the box. It's designed for workflows where you direct several agents in parallel — each in its own isolated workspace — rather than doing all of the work yourself, and automating repetitive tasks. With Node.js installed and your copy of the project ready, the next step is to install the app and connect that repository. @@ -20,7 +20,7 @@ In this lesson, you will: Your team is adopting AI agents to work through a growing backlog. The Copilot app gives you one place to direct that work — picking up issues, running agents, reviewing changes, and merging pull requests. This lesson gets you installed, connected, and comfortable starting a conversation about your project. > [!NOTE] -> An eligible Copilot plan is required — Copilot Student or any paid plan (Pro, Pro+, Business, or Enterprise). If you are on Copilot Business or Copilot Enterprise, your administrator must enable the **Copilot CLI** policy before the app will work. +> An eligible Copilot plan is required — Copilot Free,Copilot Student or any paid plan (Pro, Pro+, Business, or Enterprise). If you are on Copilot Business or Copilot Enterprise, your administrator must keep the **GitHub Copilot app** policy enabled. ## Install and configure the GitHub Copilot app @@ -29,13 +29,12 @@ To use the GitHub Copilot app the first step, as you might imagine, is to instal 1. In a browser, open the [landing page for the GitHub Copilot app][download-app]. 2. Download the app for your platform and install it following the instructions provided on the landing page. 3. Open the app once it's installed. -4. Select **Sign in to GitHub** and follow the prompts to authenticate. If you use GitHub Enterprise Server, choose **Use GitHub Enterprise** and enter your server address when prompted. -5. After authenticating, you'll be asked about connecting your repositories. Select the Tailspin Toys repo you just created, which should be named `/tailspin-toys`. -6. Select **Continue** to continue the onboarding. -7. When prompted for a theme, select the one which brings you the most joy, then select **Finish**. - -> [!NOTE] -> If your copy of Tailspin Toys didn't appear in the list automatically, you can add it after completing the onboarding process in the app. When completed, the Copilot app will bring you to the home screen. From there you can select **Choose from GitHub**, and search for your repo by name (\/tailspin-toys), then select it. Your repo will now be added to the Copilot app! +4. Select **Sign in to GitHub** and follow the prompts to authenticate. If you use GitHub Enterprise Cloud with data residency, choose **Use GitHub Enterprise** and enter your `*.ghe.com` hostname when prompted. GitHub Enterprise Server is not supported. +5. If onboarding offers repository selection, select the Tailspin Toys repository you created from the template. You can also skip repository selection and add the project after onboarding. +6. Choose a theme when prompted, then finish onboarding. +7. Look for your repository under **Sessions** in the sidebar. If it is already listed, you do not need to add it again. +8. If the repository is not connected yet, select **+** next to **Sessions** to create a new session, then select **Add GitHub repository**. Use the owner and repository name you recorded in the prerequisites lesson. +9. Confirm your repository appears in the sidebar. In the layout used here, repository folders such as `tailspin-toys` are grouped under **Sessions**, with individual sessions beneath each repository. ## Get oriented in the workspace @@ -46,8 +45,8 @@ With your project connected, take a moment to learn your way around. The app org - **Issues** - your issues, surfaced the same way. From here you can browse and filter issues and start a session from an issue. - **Automations** — saved agent tasks that run on a schedule or on demand. These are great for managing todo lists, regular project maintenance, or other bits of tedium you'd like to offload. The wrap-up links to these as a next step, not another workshop exercise. - **Customize** - add features and functions to the Copilot app in the form of MCP servers, plugins, skills, and other components. You'll use it to configure Playwright MCP. -- **Chats** — lightweight conversations for questions and brainstorming that don't need a branch or workspace of their own. You'll try one at the end of this lesson. -- **Sessions** — where agents do their work. Each session runs in its own isolated workspace, so you can run several at once without their changes colliding. You'll start your first session when you add star ratings. +- **Chats** — lightweight conversations for questions and brainstorming that don't need a branch or workspace of their own. This section appears after you start your first chat. If it is not visible, select **+** next to **Sessions** to start your first chat. +- **Sessions** — groups repository folders and their agent sessions. Select a repository name, such as `tailspin-toys`, to open its repository view, or select a session beneath it to return to that conversation. Each session runs in its own isolated workspace, so you can run several at once without their changes colliding. You'll start your first session when you add star ratings. As you work through the workshop, you'll explore the workspace! @@ -58,7 +57,7 @@ As you work through the workshop, you'll explore the workspace! There's likely not a single project without a backlog, and Tailspin Toys isn't any different. Let's explore the backlog that currently exists, which was created when you created your template. -1. Select **Issues** in the sidebar. +1. Under **Sessions** in the sidebar, select the Tailspin Toys repository folder, not an individual session beneath it. Then select **Issues** in the repository's top navigation. 2. Find these issues by title rather than assuming their issue numbers: - Allow users to filter games by category and publisher @@ -73,7 +72,7 @@ There's likely not a single project without a backlog, and Tailspin Toys isn't a A great way to get comfortable with the app is to use it to learn about the *app itself* — and a **quick chat** is exactly the right tool for that. Quick chats let you ask a question or brainstorm without creating a branch or worktree, so they're perfect for a fast, throwaway question — no session required. -1. In the sidebar, select **+** next to **Chats** to open a new chat. +1. In the sidebar, select **+** next to **Chats** to open a new chat. If **Chats** is not visible yet, select **+** next to **Sessions** to start your first chat; **Chats** appears afterward. 2. Ask the app how its own sessions work: ```plaintext diff --git a/docs/real-world-development/app/2-add-star-rating.md b/docs/real-world-development/app/2-add-star-rating.md index df4cb6ca..af919995 100644 --- a/docs/real-world-development/app/2-add-star-rating.md +++ b/docs/real-world-development/app/2-add-star-rating.md @@ -3,7 +3,7 @@ title: "Lesson 2 - Add star ratings: a quick win" description: "Start your first agent session in the GitHub Copilot app, make a small change to the game cards, and merge it as your first pull request." authors: - geektrainer -lastUpdated: 2026-07-09 +lastUpdated: 2026-10-22 --- Now that you've toured the workspace and used a quick chat, it's time to start an **agent session** and make your first change to the project. You'll keep it small: the games already have a star rating in their data, but the game cards on the home page don't show it yet. You'll ask the agent to surface it, review the change, and merge it as your first pull request. @@ -31,7 +31,7 @@ Inside a session you'll see three things: the **conversation** with the agent, t Let's start a new session to begin exploring the project and implementing our feature. During [app setup][prior-lesson], you added your project from its GitHub repository. We'll create a new session for that repository and request our change. 1. Return to (or open) the GitHub Copilot app. -2. Select the **+** next to **Projects**. +2. Select **+** at the top of the sidebar to start a session. 3. Select `tailspin-toys` for the repo. 4. Choose a **new working tree** and **Interactive** mode below the prompt box. Use the following prompt to request the change: @@ -47,7 +47,7 @@ Copilot app begins work by first creating a new worktree, an isolated copy of th All AI-generated changes deserve a review before they're merged, even small ones. Let's explore the changes, right here in Copilot app. -1. In the upper right-hand corner of the app, select **Toggle review panel**. This will open the diff screen with all the outstanding changes made by Copilot. +1. In the upper right-hand corner of the app, select **Toggle review panel**. In the panel that opens, select **Changes** to see the changed files and their diffs. ![The GitHub Copilot app top toolbar with an arrow pointing to the Toggle review panel button to the right of Create PR](../../_images/app-2-review-panel.png) @@ -97,10 +97,11 @@ You've now created the feature! It's time to create a pull request (PR) to merge 1. Select **Create PR** in the upper right corner. 2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate. -3. Copilot gets to work on creating the PR. -4. Select the **PR** bubble just above chat to open your PR in the review pane to see your pull request. You can review the PR as needed here. -5. Once ready, select **Ready to merge**. -6. Select **Merge pull request** on the new dialog window to merge your pull request! +3. If Copilot explains that repository policy requires a matching issue before creating the PR, confirm that it should follow that process. +4. Copilot gets to work on creating the PR. +5. Select the **PR** bubble just above chat to open your PR in the review pane to see your pull request. You can review the PR as needed here. +6. Once ready, select **Ready to merge**. +7. Select **Merge pull request** on the new dialog window to merge your pull request! ## Summary and next steps diff --git a/docs/real-world-development/app/3-agent-modes.md b/docs/real-world-development/app/3-agent-modes.md index dc6c1411..e30712a8 100644 --- a/docs/real-world-development/app/3-agent-modes.md +++ b/docs/real-world-development/app/3-agent-modes.md @@ -3,7 +3,7 @@ title: "Lesson 3 - Agent modes: Plan and Autopilot" description: "Explore agent modes: use Plan to agree on an approach, Autopilot to build filtering from an issue, and Interactive to review and verify the result." authors: - geektrainer -lastUpdated: 2026-10-05 +lastUpdated: 2026-10-22 --- We started by adding a small feature into our project. But larger changes require a more robust process. Fortunately, the GitHub Copilot app is built to work with an organization's existing flow, ensuring we build the right things the right way. This is the first of several lessons where you will follow a typical agent-driven development process, starting by using an issue to generate a new feature, ensuring the code is valid, the feature behaves as expected, and eventually merged successfully into the project. @@ -13,7 +13,7 @@ We started by adding a small feature into our project. But larger changes requir To start, in this lesson, you will: -- started a new agent session from a GitHub issue. +- start a new agent session from a GitHub issue. - define requirements in **Plan** mode. - implement the new feature using **Autopilot** mode. - review the code. @@ -56,13 +56,16 @@ Start in Plan mode, review the plan, then use Autopilot to implement it. Confirm the star-rating PR is merged and your local `main` is up to date before starting. -1. Select **Issues** and open **Allow users to filter games by category and publisher**. +1. Under **Sessions** in the sidebar, select the Tailspin Toys repository folder, then select **Issues** in the repository's top navigation. Open **Allow users to filter games by category and publisher**. This is an existing seeded issue; you do not need to create another one. 2. Select **New session** and choose a **new working tree** based on the updated `main`. ![The issue view in the GitHub Copilot app with an arrow pointing to the New session button](../../_images/app-new-session-from-issue.png) 3. Confirm the issue is attached to the session and select **Plan** from the mode selector. +> [!NOTE] +> If Node.js or npm is not found, ask the agent to run `node --version` and `npm --version`. If they work in your terminal but not in the session, check the app's PATH or version-manager setup, then fully quit and reopen the app. Retry the failed operation and checks; do not reinstall npm solely because the agent cannot find it. + ## Plan the filtering feature Planning gives you a chance to review the approach before Copilot writes code. Since you started from the issue, Copilot already has the feature request as context. Send: @@ -77,7 +80,7 @@ The plan should include lint, unit tests, E2E tests, and type checking using the ## Explicitly approve Autopilot -Once you're happy with the plan, select **Approve and implement with autopilot**, or the equivalent option in your version. Confirm the mode indicator shows **Autopilot**. +Once you're happy with the plan, select **Approve and implement this plan**, or the equivalent option in your version. Verify the active mode rather than assuming approval switches it. Confirm the mode indicator shows **Autopilot**. Copilot will begin work on the implementation! You'll notice it will iterate through the process, walking through the established plan, generating code, and even running tests. @@ -104,13 +107,19 @@ Ok, the code looks good - but does it run? Let's start the app like we did befor ``` 2. In a few moments the app will start and a browser window will open inside the Copilot app. -3. Confirm rated game cards display their value out of five. -4. When finished, ask Copilot to stop the dev server it started for this session by using the following prompt: +3. Select a category and confirm the results match it. Clear the filter, then select a publisher and confirm the results match that publisher. +4. Combine category and publisher filters and compare the results with the issue and your approved plan. If multiple categories are supported, verify the agreed combination behavior. +5. Exercise a combination with no matching games and check the empty state. Clear or reset the filters and confirm the full list returns. +6. When finished, ask Copilot to stop the dev server it started for this session by using the following prompt: ```plaintext Stop the dev server and close the browser canvas. ``` +## Keep this session for the next lessons + +Do not create or merge the filtering PR yet. Keep this session, worktree, and branch for Lessons 4 through 8. Next, you'll apply custom instructions to the filtering code, then add the skill and QA improvements before creating and merging the combined PR in Lesson 8. You can leave the session idle after stopping its dev server; return to the same session for the next lesson. + ## Summary and next steps You've used different agent modes to build and review a feature. In this lesson, you: diff --git a/docs/real-world-development/app/4-custom-instructions.md b/docs/real-world-development/app/4-custom-instructions.md index 8583a080..c292c208 100644 --- a/docs/real-world-development/app/4-custom-instructions.md +++ b/docs/real-world-development/app/4-custom-instructions.md @@ -64,8 +64,9 @@ While the files already built are a good start, there's still some gaps. Let's m > Because instructions files have a large impact on the code generated by Copilot, care should be taken in ensuring they clearly guide Copilot. You can always have Copilot create a first version, followed by a review by you to ensure the updates meet your requirements. You can also find a [collection of instructions files on Awesome Copilot][awesome-copilot], which serves as a great starting point. 1. In the same files canvas, navigate to `.github/copilot-instructions.md`. -2. Locate the **Code formatting requirements** header, which should be about halfway down in the file. -3. Add the following as the last bullet point below that header: +2. Switch to the editable source view by selecting the code button (the `<>` icon) in the file toolbar. +3. Locate the **Code formatting requirements** header, which should be about halfway down in the file. +4. Add the following as the last bullet point below that header: ```plaintext All new TypeScript should contain TSDocs comments for documentation purposes. diff --git a/docs/real-world-development/app/6-mcp-playwright.md b/docs/real-world-development/app/6-mcp-playwright.md index cd9a4ff9..a32c54bc 100644 --- a/docs/real-world-development/app/6-mcp-playwright.md +++ b/docs/real-world-development/app/6-mcp-playwright.md @@ -39,8 +39,8 @@ There are many other MCP servers available that provide access to different tool You manage MCP servers through **Customize** in the sidebar. Servers configured for your repositories or Copilot CLI may already be available in the app, so check before adding a duplicate. The [app customization documentation][customize-app] covers the available options. 1. Select **Customize** in the sidebar. -2. Select **MCP**, then check **Installed** for an existing Playwright server. -3. If needed, find **Playwright** among the available servers, or use the custom-server flow documented by the publisher. +2. Open the **All types** dropdown and select **MCP**, then check **Installed** for an existing Playwright server. +3. If Playwright is not already installed, find **Playwright** among the available servers and then select **Add server** 4. Review the publisher, configuration, and any installation prompts before approving them. Follow the prompts to add the server; organization policy or missing prerequisites can block setup. 5. Return to the filtering session in **Interactive** mode and confirm the Playwright MCP tools are available. diff --git a/docs/real-world-development/app/8-create-pull-request.md b/docs/real-world-development/app/8-create-pull-request.md index e616a5bb..a7c65657 100644 --- a/docs/real-world-development/app/8-create-pull-request.md +++ b/docs/real-world-development/app/8-create-pull-request.md @@ -3,7 +3,7 @@ title: "Lesson 8 - Create and merge the feature PR" description: "Review filtering, instructions, the skill update, QA profile, and tests together, then create a PR and use Agent Merge." authors: - geektrainer -lastUpdated: 2026-09-17 +lastUpdated: 2026-10-22 --- Your filtering implementation, instruction updates, skill update, quality assurance (QA) profile, and tests are saved on one branch. It's time to review them together and open a pull request. You merged the star-rating pull request (PR) yourself; this time you'll allow **Agent Merge** to manage the process. @@ -33,8 +33,8 @@ With all of your code created and reviewed, let's allow agent merge to manage th 1. Use the agent picker to select **Default agent**. 2. Select the dropdown next to **Create PR**. -3. Select **Agent merge**. The button changes to **Agent merge**. -4. Select **Agent merge** to start the agent merge process. +3. Select **Agent Merge**. The button changes to **Agent Merge**. +4. Select the **Agent Merge** button to start the process. Choosing the dropdown option alone does not start it. The agent merge process kicks off. It will: @@ -47,9 +47,16 @@ The agent merge process kicks off. It will: Let's let agent merge also merge the PR once everything passes! -5. Select the dropdown next to **Agent merge**. -6. Ensure there's a check next to **Merge pull request**. +5. Review the PR diff and verification evidence before granting merge permission. +6. Select the dropdown next to **Agent Merge**. +7. Ensure there's a check next to **Merge pull request**. +8. Explicitly ask the agent to merge: + ```plaintext + Merge the PR once all required checks and approvals pass. Do not bypass repository protections. + ``` + +9. Follow its progress and resolve any reported blockers. Confirm the PR status is **Merged** before continuing; enabled merge permission or a running agent is not confirmation of a completed merge. > [!IMPORTANT] > Agent Merge does not bypass repository protections or missing permissions. Resolve those blockers before continuing. diff --git a/docs/real-world-development/app/README.md b/docs/real-world-development/app/README.md index 3c3e2087..39731099 100644 --- a/docs/real-world-development/app/README.md +++ b/docs/real-world-development/app/README.md @@ -3,7 +3,7 @@ slug: real-world-development/app title: "GitHub Copilot app" authors: - geektrainer -lastUpdated: 2026-09-17 +lastUpdated: 2026-10-22 --- The **[GitHub Copilot app](https://docs.github.com/copilot/concepts/agents/github-copilot-app)** is a desktop application built on Copilot CLI that brings agent-driven development into a single, focused workspace. It adds parallel agent sessions, switchable session modes, shared canvases, and native GitHub issue and pull request management — including **Agent Merge**, which shepherds a pull request through rebases, review feedback, continuous integration (CI) fixes, and merge. @@ -18,7 +18,7 @@ The workshop follows one continuous Tailspin Toys workflow: 6. Add the Playwright Model Context Protocol (MCP) server and use it to explore filtering in a browser. 7. Create a quality assurance (QA) custom agent and use it to review requirements, coverage, and verification evidence. 8. Review the complete filtering change and use Agent Merge for the second PR. -9. Use the existing Database Explorer canvas, then create and test a repository-backed triage canvas. +9. Check canvas availability, then use Database Explorer and create and test a repository-backed triage canvas. If required capabilities are unavailable, record the blocker and use the read-only alternative or continue to the wrap-up. To keep the workshop focused, you'll create two PRs: star ratings, then filtering with the instruction updates, skill update, QA profile, and tests. Start each from updated `main`. The filtering and quality workflow shares one session, worktree, and branch so you can build on your work as you explore each tool. The final canvas exercise stays in its session so you can focus on creating and testing the shared surface rather than repeating the PR workflow. @@ -53,7 +53,7 @@ Before attending this workshop, please ensure you have: > Because the Copilot app runs on your own machine rather than in a codespace, [the prerequisites exercise][ex0] walks you through installing Node.js and creating your copy of the project before you install the app. > [!NOTE] -> If you are using Copilot Business or Copilot Enterprise, your administrator must enable the **Copilot CLI** policy before you can use the app. +> If you are using Copilot Business or Copilot Enterprise, your administrator must keep the **GitHub Copilot app** policy enabled. This is separate from the Copilot CLI policy. ## Get Started