diff --git a/copilot-app/0-prerequisites.md b/copilot-app/0-prerequisites.md new file mode 100644 index 00000000..f01edeab --- /dev/null +++ b/copilot-app/0-prerequisites.md @@ -0,0 +1,82 @@ +--- +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." +--- + +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, using both the Tailspin Toys app, built on Astro, and of course the GitHub Copilot app. Before you get started, let's ensure Node.js is installed locally, then install the Copilot app. + +In this lesson, you will: + +- install Node.js so the project's tests can run on your machine. +- create your own copy of the Tailspin Toys project from the template. + +## Install Node.js + +Several lessons ask an agent to build features and run the Tailspin Toys test suite locally, which needs **[Node.js][nodejs]** — the only runtime the project requires. Install version **22 or newer**; the current **LTS** release is a safe choice. + +The simplest option on every platform is the official installer: + +1. In your operating system, open a terminal window using Windows Terminal, macOS terminal, or whatever you typically use. +2. Run the following command to confirm you have at least Node.js 22 or higher installed: + + ```shell + node --version + ``` + +3. If you see `v22` or a higher number, 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. + +4. Open the [Node.js download page][node-download]. +5. Download the **LTS** build for your operating system. +6. Run the installer and accept the defaults. On Windows, keep the **Add to PATH** option selected. +7. Once installed, open a new terminal window. +8. Confirm the install in the new terminal window by running the following: + + ```bash + node --version + ``` + +9. You should see `v22.x.x` or higher. + +> [!TIP] +> Prefer containers? If you have **[Docker][docker]**, you can use the repository's [dev container][dev-containers] instead of installing Node.js locally — it bundles Node for you. You don't need both. + +## Set up the lab repository + +You'll work against your own copy of the Tailspin Toys project. Create it now from the [template repository][template-repository]. The new repository contains every file the lab needs, and you'll connect it to the app in the next lesson. + +1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`. +2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**. + + ![The Use this template button with Create a new repository selected from the dropdown](images/app-0-use-template.png) + +3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to GitHub Copilot. + + ![The Create a new repository form with github-samples/tailspin-toys set as the template and the repository name filled in](images/app-0-create-repository.png) + +4. Make a note of the repository path you created (**organization-or-user-name/repository-name**), as you will be referring to this later in the lab. + +> [!NOTE] +> When you create your repository from the template, a backlog of GitHub issues is created for you automatically. You'll work from these issues throughout the workshop — there's nothing to file yourself. + +## Summary and next steps + +You're set up! You installed Node.js so the project can build and test on your machine, and you created your own copy of the Tailspin Toys repository from the template. + +Next, you'll install the GitHub Copilot app, connect the repository you just created, and get oriented in the workspace. Continue to [Lesson 1 - Installing the GitHub Copilot app][next-lesson]. + +## Resources + +- [Download Node.js][node-download] +- [Creating a repository from a template][template-repository] +- [About the GitHub Copilot app][about-copilot-app] + +[next-lesson]: 1-install-copilot-app.md +[nodejs]: https://nodejs.org/ +[node-download]: https://nodejs.org/en/download +[docker]: https://www.docker.com/products/docker-desktop/ +[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers +[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 diff --git a/copilot-app/1-install-copilot-app.md b/copilot-app/1-install-copilot-app.md new file mode 100644 index 00000000..d22f5a1d --- /dev/null +++ b/copilot-app/1-install-copilot-app.md @@ -0,0 +1,97 @@ +--- +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." +--- + +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. With Node.js installed and your copy of the project ready, the next step is to install the app and connect that repository. + +In this lesson, you will: + +- install the GitHub Copilot app and sign in. +- add your project to the app from its GitHub repository. +- get oriented in the workspace, including the backlog the template seeded for you. +- try a quick chat to learn about the app itself. + +## Scenario + +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. + +## Install and configure the GitHub Copilot app + +To use the GitHub Copilot app the first step, as you might imagine, is to install it. Versions are available for Windows, macOS and Linux. Let's install the app, authenticate, and add our Tailspin Toys repo to the app. + +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! + +## Get oriented in the workspace + +With your project connected, take a moment to learn your way around. The app organizes everything into a few areas in the sidebar: + +- **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 in the next lesson. +- **Quick 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. +- **My work** — your issues and pull requests, surfaced through the app's **native GitHub integration**. From here you can browse and filter issues and pull requests, check CI status, start a session from an issue, and review pull requests — all without leaving the app. +- **Automations** — saved agent tasks that run on a schedule or on demand. You'll create one near the end of the harness. + +### Find your seeded backlog + +Because the app integrates with GitHub natively, the work waiting in your repository shows up right inside the app. When you created your repository from the template, a backlog of issues was filed for you — let's confirm it's there. + +1. Select **My work** in the sidebar. +2. Confirm you see the three issues the template seeded for your backlog: + + - Allow users to filter games by category and publisher + - Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments + - Stretch Goal: Implement pagination on the game list page + +3. Select an issue to read its details. Each issue is also a launch point for an agent session — you'll start work from these issues later in the harness. + +> [!NOTE] +> The list of items in My work is automatically filtered to only display items from the repositories you've added to Copilot app. Want to see work items from other repos? Add them to the app! + +## Try a quick chat + +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 **Quick chats** to open a new chat. +2. Ask the app how its own sessions work: + + ```plaintext + How does the GitHub Copilot app use worktrees? + ``` + +3. Read the response in the conversation view. You'll see that each session runs in its own isolated git worktree — the detail that lets you run several agents in parallel without their changes colliding. You can continue the conversation or start a new chat at any time. + +## Summary and next steps + +Congratulations! You've installed the GitHub Copilot app, connected your project, and explored your workspace. You learned how to: + +- install the app and sign in to GitHub. +- add a project from its GitHub repository. +- get oriented in the workspace and find your seeded backlog in **My work**. +- use a quick chat to ask a fast, throwaway question. + +Next, you'll start your first agent session and make your first change to the project — showing a star rating on the game cards. Continue to [Lesson 2 - Running your first agent session][next-lesson]. + +## Resources + +- [About the GitHub Copilot app][about-copilot-app] +- [Getting started with the GitHub Copilot app][getting-started] +- [Working with agent sessions in the GitHub Copilot app][agent-sessions] + +[ex0]: 0-prerequisites.md +[next-lesson]: 2-add-star-rating.md +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[download-app]: https://gh.io/app diff --git a/copilot-app/2-add-star-rating.md b/copilot-app/2-add-star-rating.md new file mode 100644 index 00000000..d1fd871e --- /dev/null +++ b/copilot-app/2-add-star-rating.md @@ -0,0 +1,131 @@ +--- +title: "Lesson 2 - Running your first agent session" +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." +--- + +In the previous lesson you toured the workspace and used a quick chat. Now 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. + +In this lesson, you will: + +- start an agent session and learn how a session is structured. +- ask the agent to make a small, focused change to the project. +- review the change in the workspace diff view. +- run the app locally to confirm the change in the browser. +- open and merge your first pull request. + +## Scenario + +Each game in Tailspin Toys can have a star rating, and it already appears on the game details page. The game cards on the home page, though, only show the title, category, publisher, and description. As a warm-up, you'll have the agent display the existing rating on each card — a tiny, self-contained change that's perfect for your first session. + +## Anatomy of a session + +A **session** is a conversation with an agent that runs in its own isolated workspace. Every session gets a **dedicated git worktree and branch**, which is what lets you run several sessions at once — one adding a feature, another fixing a bug — without their changes colliding. Your sessions appear in the sidebar grouped by repository; select any one to switch to it. + +Inside a session you'll see three things: the **conversation** with the agent, the agent's **tool activity** as it explores and edits files, and the list of **changed files** with their diffs. + +## Start a session and request our change + +Let's start a new session to begin exploring the project and implementing our feature. In a [prior lesson][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 **Home screen**. +3. Ensure `tailspin-toys` is selected for the repo. + + ![The GitHub Copilot app prompt box with the repository selector set to tailspin-toys and the model selector shown beneath the prompt](images/app-2-start-session.png) + +4. Use the following prompt to request the change: + + ```plaintext + On the game cards, show each game's star rating. The Game type already includes a starRating field — it's a number out of 5, or null when a game hasn't been rated yet. Display it on each card in src/components/GameCard.astro, and when starRating is null show "No rating yet" instead. Keep the change small and don't restructure the card layout. + ``` + +> [!NOTE] +> Notice how the prompt contained the name of the file for Copilot to update. While it's not required at all to specify which files Copilot should include in its work, pointing it in the right direction both helps Copilot quickly generate code and reduce token usage. + +5. Select Enter to send the prompt to Copilot. + +Copilot app begins work by first creating a new worktree, an isolated copy of the project. It then explores the project, locating the necessary files to update to add the new feature. It will then create the necessary code. You've now added a new feature with Copilot app! + +## Review the diff + +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. + + ![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) + +2. You should notice code added to `GameCard.astro`, the core file used to display game details. It should be similar to the following — a small block that renders the rating when present and falls back to "No rating yet" when `starRating` is `null`: + + ```astro + {game.starRating !== null ? ( + + ★ {game.starRating} / 5 + + ) : ( + + No rating yet + + )} + ``` + +> [!NOTE] +> Because Copilot, like all generative AI tools, is probabilistic rather than deterministic, the exact code may vary from the above. But it should be relatively similar. + +## Check the changes + +Of course we shouldn't just read the code and assume it works. We should visually test everything as well! To do so we'll need to start the app from the terminal, then confirm everything works. Fortunately there's a terminal button in the upper right that will allow us quick access to the worktree the Copilot app created! + +1. In the upper right hand corner of the Copilot app, select **Open** next to the terminal icon. + + ![The GitHub Copilot app top toolbar with an arrow pointing to the Open button next to the terminal icon](images/app-open-terminal.png) + +2. Enter the following command in the terminal window to start the web app's dev server: + + ```shell + npm run dev + ``` + +3. Once the server starts (this will just take a moment), open a browser window. +4. Navigate to http://localhost:4321. +5. You should now see star ratings on all the games on the landing page! +6. Return to the terminal window. +7. Select Ctrl+C to stop the dev server. + +## Open and merge your first pull request + +Your change looks good — now it's time to ship it! You'll ask the agent to open a pull request, then review and merge it yourself on github.com. For now we'll manage this manually. In an upcoming lesson we'll explore how Copilot can handle some of the work for you automatically. + +1. In the upper right hand corner, select **Create PR**. +2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate. +3. Copilot gets to work on creating the PR. + +Once the PR is created, Copilot will monitor any workflows on the repository that need to run. After a few moments, the button in the upper right will change to **Ready to merge**. This will be your indication your PR is ready to merge! + +4. Select **Ready to merge**. +5. Select **Merge pull request** on the new dialog window to merge your pull request! + +You've now pushed a new feature to the website! + +## Summary and next steps + +You've started your first agent session and shipped your first change! Specifically, you: + +- started an agent session and learned how sessions are structured. +- directed the agent to make a small, focused change to the game cards. +- reviewed the change in the workspace diff view. +- ran the app locally to confirm the star rating in the browser. +- opened a pull request and merged it yourself on github.com. + +Next, you'll use the app to add a custom instructions standard to the repository — starting from one of the issues in your backlog. Continue to [Lesson 3 - Guiding Copilot with custom instructions][next-lesson]. + +## Resources + +- [Working with agent sessions in the GitHub Copilot app][agent-sessions] +- [About the GitHub Copilot app][about-copilot-app] +- [Managing issues and pull requests with the GitHub Copilot app][managing-issues-prs] + +[prior-lesson]: 1-install-copilot-app.md#install-and-configure-the-github-copilot-app +[next-lesson]: 3-custom-instructions.md +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests diff --git a/copilot-app/3-custom-instructions.md b/copilot-app/3-custom-instructions.md new file mode 100644 index 00000000..a493a4a4 --- /dev/null +++ b/copilot-app/3-custom-instructions.md @@ -0,0 +1,156 @@ +--- +title: "Lesson 3 - Guiding Copilot with custom instructions" +description: "Use the GitHub Copilot app to add a custom instructions standard to your repository, starting from an issue in your backlog and merging the change as a pull request." +--- + +Context is key when working with generative AI. If a task needs to be done a particular way — or there's background information Copilot should know — you want that context available. One of the most powerful tools for this is [instruction files][instruction-files], which describe not just *what* code you want but *how* it should be structured. In this lesson you'll add a documentation standard to your repository, and you'll do it the way you'll do most work from here on: starting from an issue in your backlog and letting the agent make the change. + +In this lesson, you will: + +- explore how repository instructions and path-scoped instruction files reach the agent. +- start a session from the instructions issue in your backlog. +- ask the agent to add a documentation standard to `.github/copilot-instructions.md`. +- review the change and merge it as a pull request. + +## Scenario + +As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include: + +- Documentation should be added to code in the form of TSDoc doc comments. +- Formatting should be documented and enforced through linting. + +Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted. + +## Instruction files + +Custom instructions allow you to provide context and preferences to Copilot, so that it can better understand your coding style and requirements. This is a powerful feature that can help you steer Copilot to get more relevant suggestions and code snippets. You can specify your preferred coding conventions, libraries, and even the types of comments you like to include in your code. You can create instructions for your entire repository, or for specific types of files for task-level context. + +There are two types of instructions files: + +- `.github/copilot-instructions.md`, a single instruction file sent to Copilot for **every** request for the repository. This file should contain project-level information — context relevant for most chat or CLI requests sent to Copilot. This could include the tech stack being used, an overview of what's being built, best practices, and other global guidance. +- `.github/instructions/*.instructions.md` files can be created for specific tasks or file types. You can use them to provide guidelines for particular languages (like TypeScript or Astro), or for tasks like creating a UI component or a new set of unit tests. + +> [!NOTE] +> When working in your IDE, instructions files are only used for code generation in Copilot Chat — not for code completions or next-edit suggestions. +> +> Copilot Chat, Copilot CLI and Copilot cloud agent use both repository-level and `*.instructions.md` files (with `applyTo` front matter) when generating code. +> +> Finally, Copilot [supports instructions files using other standards][custom-instructions-support], including AGENTS.md and CLAUDE.md files. + +### Best practices for managing instructions files + +A full conversation about creating instructions files is beyond the scope of the workshop. However, the examples provided in the sample project show a representative approach. At a high level: + +- Keep instructions in `copilot-instructions.md` focused on project-level guidance, such as a description of what's being built, the structure of the project, and global coding standards. +- Use `*.instructions.md` files to provide specific instructions for file types (unit tests, Astro components, the data layer), or for specific tasks. +- Use natural language. Keep guidance clear. Provide examples of how code should (and shouldn't) look. + +There isn't one specific way to create instructions files, just as there isn't one specific way to use AI. You will find through experimentation what works best for your project. + +> [!TIP] +> Every project using GitHub Copilot should have a robust collection of instruction files. As you explore the ones in this project, you may notice there are instructions files for numerous types of code files. +> +> Looking for templates or a starting point? Explore [awesome-copilot][awesome-copilot], a repository full of instruction files, custom agents, and other resources. + +## Explore the custom instructions files in this project + +Take a moment to read the instruction files this repository ships with — there's one core `copilot-instructions.md` and a collection of `*.instructions.md` files for various tasks. Open these in your editor or the GitHub web UI. + +1. Open your repository on GitHub. +2. Navigate to `.github/copilot-instructions.md`. +3. Explore the file, noting the brief description of the project plus sections such as **Agent notes**, **Code standards**, **Scripts**, and **Repository Structure**. Under **Code standards**, note the nested **GitHub Actions Workflows** guidance. These are applicable to any interactions you'd have with Copilot. +4. Navigate to the `.github/instructions` folder and look around. Note there are instructions for Astro files, the Drizzle data layer, tests, and more. +5. Open `.github/instructions/unit-tests.instructions.md`. Note the `applyTo` field at the top — this sets a glob (relative to the repo root) that determines which files the instructions apply to. Here, any TypeScript test file (for example, one matching `**/*.test.ts`) will match. +6. Note the instructions specific to creating unit tests for this project. +7. Finally, open `.github/instructions/drizzle.instructions.md` and scroll to the bottom. Note the links to other instruction files (like `unit-tests.instructions.md`) and existing files in the project. This lets you break larger instruction sets into smaller, reusable files, and point Copilot at examples to follow when generating code. (Paths there are relative to the instruction file rather than the repo root.) + +> [!NOTE] +> The **Code formatting requirements** section in `copilot-instructions.md` documents the project's coding standards, but it doesn't yet require in-code documentation. In the next steps, you'll add rules for TSDoc doc comments and file comment headers. + +## Start from the instructions issue + +In the previous lesson you started a session from a direct prompt. Most work, however, starts with an issue. Let's create a new session based off an issue filed to update the instructions files, then make the request for the update. + +> [!NOTE] +> Because instructions files have a large impact on the code generated by Copilot, care should be taken in ensuring they clearly guide Copilot. Having Copilot create a first version, like you'll do in this lesson is a great approach, followed by a review by you to ensure the updates meet your requirements. + +1. Select **My work** in the sidebar +2. Select the issue titled **Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments** to open the issue. +3. Select **New session** in the upper right to start a new session based on the issue. + + ![The issue view in the GitHub Copilot app with an arrow pointing to the New session button in the upper right](images/app-new-session-from-issue.png) + +4. Use the following prompt to request Copilot update the instructions files to meet the requirements documented in the issue: + + ```plaintext + Following this issue, make the updates to the instructions files in this project to meet the requirements documented. Don't create the PR quite yet! + ``` + +Copilot will make the updates! + +## Review the change + +Let's both read through the updates Copilot made, but also ask it to provide an example of the code it will now generate based on the updated instructions. + +1. Select **Changes** in the upper right to open the code changes. + + ![The session panel tabs in the GitHub Copilot app with an arrow pointing to the Changes tab](images/app-select-changes.png) + +2. Review the updated instructions file. Confirm it has the guidelines about adding documentation and comments to the code. + +> [!NOTE] +> Because AI is probabilistic rather than deterministic, the exact text will vary. + +3. Use the following prompt to ask Copilot to create an example of the code it will now generate: + + ```plaintext + Do not make any updates, but show me what the code would look like. Based on the new instructions, if I asked Copilot to create a new library component to return all Publishers what would that code look like? + ``` + +4. Review the code Copilot proposes. Note the TSDoc doc comments and the file header comment it includes — exactly what the updated instructions ask for. + +You've now updated the instructions files in the project and seen the impact it will have! + +## Open and merge the pull request + +Instructions files become assets in the repository, meaning they're shared with the rest of the team. Let's create a PR with our work, just like we would any other asset! + +1. In the upper right hand corner, select **Create PR**. +2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate. +3. Copilot gets to work on creating the PR. + +Once the PR is created, Copilot will monitor any workflows on the repository that need to run. After a few moments, the button in the upper right will change to **Ready to merge**. This will be your indication your PR is ready to merge! + +4. Select **Ready to merge**. +5. Select **Merge pull request** on the new dialog window to merge your pull request! + +> [!NOTE] +> With the standard merged into your default branch, it becomes part of the project for everyone — and for every new session. When you start the filtering session in the next lesson from an up-to-date default branch, the agent will follow this standard automatically. You'll see the TypeScript it generates include TSDoc doc comments without being asked — a small but real demonstration of instructions shaping generated code. + +## Summary and next steps + +You explored how the app picks up context from instruction files, then used a session to add and merge a repository-wide standard. Specifically, you: + +- explored the repository's `copilot-instructions.md` and path-scoped `*.instructions.md` files. +- started a session from the instructions issue in your backlog. +- asked the agent to add a documentation standard to `.github/copilot-instructions.md`. +- reviewed the change and merged it as a pull request. + +Next, you'll build the filtering feature in a fresh session — and watch it pick up the standard you just merged. Continue to [Lesson 4 - Building a feature with Autopilot][next-lesson]. + +## Resources + +- [Instruction files for GitHub Copilot customization][instruction-files] +- [Customizing the GitHub Copilot app][customize-app] +- [Best practices for creating custom instructions][instructions-best-practices] +- [Awesome Copilot — a collection of instruction files and other resources][awesome-copilot] + +[next-lesson]: 4-build-filtering.md +[instruction-files]: https://docs.github.com/copilot/customizing-copilot/about-customizing-github-copilot-chat-responses +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[instructions-best-practices]: https://docs.github.com/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository +[awesome-copilot]: https://awesome-copilot.github.com/github +[custom-instructions-support]: https://docs.github.com/copilot/reference/custom-instructions-support +[ui-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/ui.instructions.md +[astro-instructions]: https://github.com/github-samples/tailspin-toys/blob/main/.github/instructions/astro.instructions.md +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests diff --git a/copilot-app/4-build-filtering.md b/copilot-app/4-build-filtering.md new file mode 100644 index 00000000..a09bb7ce --- /dev/null +++ b/copilot-app/4-build-filtering.md @@ -0,0 +1,177 @@ +--- +title: "Lesson 4 - Building a feature with Autopilot" +description: "Use Plan and Autopilot modes in the GitHub Copilot app to build a static, client-side filtering feature, watch it inherit your documentation standard, and verify it with an agent skill." +--- + +We've made a couple of small updates to our project thus far. But more robust changes require a more robust process. Fortunately, the GitHub Copilot app is built to work with our existing flow, ensuring we build the right things the right way. This is the first of three lessons where you will follow a typical development process, starting by using an issue to generate a new feature and an agent skill to run the validation tests and linters. + +In this lesson, you will: + +- start a fresh session from the filtering issue. +- use **Plan** mode to plan the feature, then **Autopilot** to build it. +- confirm the generated code follows the documentation standard you merged earlier. +- verify your work with the project's `quality-checks` skill. + +## Scenario + +The home page lists every game, but visitors can't narrow the list down. The filtering issue asks you to let them filter games by **category** and **publisher**. Let's use Copilot to implement that functionality. + +## Background + +Introducing AI coding agents to your development flow doesn't change the fundamentals. If anything, they become even more important! Most developers follow a flow that resembles: + +1. Open a filed issue with details of what needs to be done. +2. Create a plan of what needs to be built. +3. Build and review the code. +4. Run the tests to validate the code. +5. Manually validate the new functionality. +6. Create a pull request (PR). +7. Once the code has been reviewed and the continuous integration process succeeds, merge the code. + +> [!NOTE] +> Depending on your team and organization, the exact specifics will vary. But most will be a variation on the theme listed above. + +By sticking to this standard approach you ensure the code generated by AI meets the requirements set forth, and goes through the same vetting process as code written by hand. + +## Session modes + +The **session mode** controls how much autonomy the agent has. You can set it from the dropdown below the prompt field and change it at any time: + +- **Interactive**: You and the agent work together. The agent suggests changes and waits for your input before proceeding. +- **Plan**: The agent creates a plan first. You review and approve the plan before the agent executes it. +- **Autopilot**: The agent works fully autonomously—writing code, running tests, and iterating without waiting for input. + +## Plan the filtering feature + +The best time to catch a potential issue is before any code is written, and the best way to do that is a bit of planning in advance. By planning with Copilot you'll ask Copilot to generate a set of steps and document the approach it will take. You can then review the plan, make any suggestions you might have to improve it, before letting Copilot generate the code based on the plan. + +Let's open the issue, start a new session, and create a plan by switching into plan mode and making the request. + +1. Select **My work** from the navigation tab. +2. Select the issue titled **Allow users to filter games by category and publisher**. +3. Select **New session** in the upper right. + + ![The issue view in the GitHub Copilot app with an arrow pointing to the New session button in the upper right](images/app-new-session-from-issue.png) + +4. Select Shift+Tab until the mode displays **Plan**. + + ![The GitHub Copilot app prompt box with an arrow pointing to the mode selector set to Plan](images/app-4-plan-mode.png) + +5. Send the following prompt. The filtering issue is already in this session's context because you started from it: + + ```plaintext + Plan the work based on the requirements documented in the issue. Please ask any clarifying questions you might have as you build the plan. + ``` + +6. The agent may ask follow-up questions as it builds the plan. Answer them based on how you'd build the feature. + +> [!NOTE] +> Because Copilot is probabilistic, the exact follow-up questions Copilot asks will vary. In fact, it might not ask any questions! This is perfectly normal. + +7. Once completed, Copilot will offer a plan summary. Review the plan. You should see it propose building queries, adding filter controls, and of course tests. Provide feedback to refine it if you'd like — the agent will incorporate your suggestions into a new version. + +## Build it with Autopilot + +With the plan created, let's let Copilot build the implementation! + +1. In the list of options in the **Plan summary** dialog, select the option closest to **Approve and implement with autopilot**. + +Copilot will begin work on the implementation! + +> [!NOTE] +> If Copilot doesn't automatically start creating the necessary code, you can prompt it to do so by using a prompt like "Go ahead and start building out the plan!". +> +> Creating the necessary updates will take several minutes. The agent edits and creates files, writes and runs tests, and iterates. Now's a good time to reflect on what you've explored so far, or to enjoy a beverage. + +## Review the changes + +All AI-generated code needs review before it's merged. Let's both review the code and run the site to ensure everything looks good. + +1. Select **Changes** in the upper right to open the code changes. + + ![The session panel tabs in the GitHub Copilot app with an arrow pointing to the Changes tab](images/app-select-changes.png) + +2. Review the changes. You should see new TypeScript and Astro files, and test files. Notice the new helper functions include TSDoc doc comments and a file header comment — the documentation standard you merged in Lesson 3, applied automatically without being asked. +3. In the upper right hand corner of the Copilot app, select **Open** next to the terminal icon. + + ![The GitHub Copilot app top toolbar with an arrow pointing to the Open button next to the terminal icon](images/app-open-terminal.png) + +4. Enter the following command in the terminal window to start the web app's dev server: + + ```shell + npm run dev + ``` + +5. Once the server starts (this will just take a moment), open a browser window. +6. Navigate to http://localhost:4321. +7. You should now see filters available on the landing page! +8. If anything doesn't look right, you can ask Copilot to make the updates! +9. Once satisfied, return to the terminal window. +10. Select Ctrl+C to stop the dev server. + +## Verify your work with the quality-checks skill + +You could eyeball the diff and call it done, but the team has a defined quality bar — and a repeatable way to check it. + +**Agent skills** let you give Copilot guidance on how to perform repeatable tasks like running tests, generating builds, or creating pull requests. A skill is a folder of instructions, scripts, and resources that the agent can load on demand. [Agent Skills is an open standard][agent-skills-repo] used by a range of agents, so the same skill works across Copilot Chat in agent mode, Copilot cloud agent, Copilot CLI, and the GitHub Copilot app. + +Skills live in the `.github/skills` folder of a project, or globally in `~/.copilot/skills`. Each skill is a folder containing a `SKILL.md` file with YAML frontmatter (a `name` and a `description`) followed by the markdown instructions: + +```yaml +--- +name: quality-checks +description: Run the project's test suites and linter to verify code changes are ready to commit, push, or merge. +--- +``` + +Skills can also include subfolders with scripts, assets, and reference material. The full structure is covered in the [agent skills specification][agent-skills-spec]. + +> [!TIP] +> Skills are loaded dynamically. The agent decides which skill applies based on the `description` field — a clear, scenario-specific description is the difference between a skill that gets used and one that gets ignored. + +## Explore the quality-checks skill + +Let's explore the skill to see what it does. + +1. Open your repository on GitHub. +2. Follow the links in your repo to open `.github/skills/quality-checks/SKILL.md` in your project. +3. Note the `name` and `description`. The description tells the agent *when* to use it — whenever code changes need to be tested, linted, or verified before a commit, push, or merge. +4. Read through the skill. Notice it documents which script runs which suite (unit tests, Playwright end-to-end tests, ESLint), in what order, and how to debug common failures — so the agent runs the checks the team's way instead of guessing. + +## Run the checks + +In the same filtering session, ask the agent to verify the work. You won't name the skill — the agent will match it from your request. + +1. Return to Copilot app. +2. Directly call the skill by using the slash command `/quality-checks` and select Enter. +3. Following the skill, the agent runs the unit tests, the linter, and the end-to-end tests, and reports the results. If anything fails, ask it to fix the issue and run the checks again until everything is green. +4. **Keep this session open.** In the next lesson you'll add the Playwright MCP server and use it to see the filtering feature working in a real browser. + +## Summary and next steps + +You built a real feature end to end and verified it against the team's bar! Specifically, you: + +- started a fresh session from the filtering issue on an up-to-date project. +- used Plan mode to plan the feature and Autopilot to build it, with static-Astro constraints. +- confirmed the generated helper followed the documentation standard you merged in Lesson 3. +- verified your work with the `quality-checks` skill. + +Next, you'll connect the Playwright MCP server and ask the agent to explore your filtering feature in a real browser. Continue to [Lesson 5 - Testing with the Playwright MCP server][next-lesson]. + +## Resources + +- [Working with agent sessions in the GitHub Copilot app][agent-sessions] +- [About Agent Skills][about-agent-skills] +- [Customizing the GitHub Copilot app][customize-app] +- [About cloud and local sandboxes for GitHub Copilot][sandboxes] + +[ex0]: 0-prerequisites.md +[ex2]: 2-add-star-rating.md +[ex3]: 3-custom-instructions.md +[next-lesson]: 5-mcp-playwright.md +[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions +[about-agent-skills]: https://docs.github.com/copilot/concepts/agents/about-agent-skills +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[agent-skills-repo]: https://github.com/agentskills/agentskills +[agent-skills-spec]: https://agentskills.io/specification diff --git a/copilot-app/5-mcp-playwright.md b/copilot-app/5-mcp-playwright.md new file mode 100644 index 00000000..e628b100 --- /dev/null +++ b/copilot-app/5-mcp-playwright.md @@ -0,0 +1,83 @@ +--- +title: "Lesson 5 - Testing with the Playwright MCP server" +description: "Add the Playwright MCP server to the GitHub Copilot app and ask the agent to manually test your filtering feature in a real browser." +--- + +In the previous lesson you created and verified the filtering feature with the project's automated test suite. Tests automate validation of code, but allowing the agent to confirm behavior is powerful. It allows an agent to respond to issues it sees in the actual UI it's creating. Let's explore how MCP allows access to external capabilities to AI agents, and add the Playwright MCP server to allow Copilot to interact with the site you're building directly. + +In this lesson, you will: + +- understand what Model Context Protocol (MCP) is and how the GitHub Copilot app uses it. +- add the Playwright MCP server from the app settings. +- ask the agent to drive a browser and explore your filtering feature. + +## Scenario + +While unit and end to end tests are important, validating updates to the UI require actually interacting with the UI. You want to allow Copilot to use the website you're working on as a user would to further automate how changes are made, providing more confidence the updates perform as expected. + +## What is Model Context Protocol (MCP)? + +[Model Context Protocol (MCP)][mcp-blog-post] provides AI agents with a way to communicate with external tools and services. By using MCP, AI agents can communicate with external tools and services in real-time. This allows them to access up-to-date information (using resources) and perform actions on your behalf (using tools). + +These tools and resources are accessed through an MCP server, which acts as a bridge between the AI agent and the external tools and services. The MCP server is responsible for managing the communication between the AI agent and the external tools (such as existing APIs or local tools like NPM packages). Each MCP server represents a different set of tools and resources that the AI agent can access. + +A couple of popular existing MCP servers are: + +- **[GitHub MCP Server](https://github.com/github/github-mcp-server)**: This server provides access to a set of APIs for managing your GitHub repositories. It allows the AI agent to perform actions such as creating new repositories, updating existing ones, and managing issues and pull requests. +- **[Playwright MCP Server][playwright-mcp-server]**: This server provides browser automation capabilities using Playwright. It allows the AI agent to perform actions such as navigating to web pages, filling out forms, and clicking buttons. + +There are many other MCP servers available that provide access to different tools and resources. GitHub hosts an [MCP registry](https://github.com/mcp) to enhance discoverability and contributions to the ecosystem. + +> [!CAUTION] +> Treat MCP servers as you would any other dependency in your project. Before using an MCP server, carefully review its source code, verify the publisher, and consider the security implications. Only use MCP servers that you trust and be cautious about granting access to sensitive resources or operations. + +## Add the Playwright MCP server + +You add and manage MCP servers from the app settings. The app includes a catalog of popular servers, so the [Playwright MCP server][playwright-mcp-server] is just a couple of clicks away. + +1. Select Ctrl+, to open the Copilot app settings page. +2. Select **MCP servers**. +3. In the search dialog, type `Playwright`. +4. Select **Playwright** from the list of **Popular MCP servers**. +5. Select **Add server** to add it to the list of available MCP servers. +6. Select Esc to close the settings dialog. + +You've now added the Playwright MCP server! + +## Ask Copilot to explore the feature via Playwright + +Let's ask Copilot to test the feature manually by using the Playwright MCP server. + +1. Use the following prompt to ask Copilot to validate the new functionality: + + ```plaintext + Start the dev server then use the Playwright MCP server to validate the functionality you just added exists. Use the details in the issue to ensure the newly added behavior matches the specs. + ``` + +Copilot will launch a browser through the Playwright MCP server, walk through each step, and report back what it found. You'll actually see it open a browser on your system to perform the tasks! + +2. Read its summary against the acceptance criteria in the issue. If something looks off, ask follow-up questions or send it back to fix the code before you open a pull request. +3. Leave this session open as we're going to close it out in the next lesson! + +Copilot has now also validated the functionality in the browser by exploring the feature like a user would. + +## Summary and next steps + +Congratulations, you used the Playwright MCP server to explore your feature in a real browser from the GitHub Copilot app! To recap, you: + +- learned what Model Context Protocol (MCP) is and how the app makes MCP tools available. +- added the Playwright MCP server from the app settings. +- asked the agent to drive a browser and explore your filtering feature. + +Your feature is built, verified, and seen working. Now it's time to ship it — using **Agent Merge** to open and merge the pull request for you. Continue to [Lesson 6 - Merging with Agent Merge][next-lesson]. + +## Resources + +- [What the heck is MCP and why is everyone talking about it?][mcp-blog-post] +- [Microsoft Playwright MCP Server][playwright-mcp-server] +- [Configuring MCP servers in the GitHub Copilot app][customize-app] + +[next-lesson]: 6-agent-merge.md +[mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/ +[playwright-mcp-server]: https://github.com/microsoft/playwright-mcp +[customize-app]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app diff --git a/copilot-app/6-agent-merge.md b/copilot-app/6-agent-merge.md new file mode 100644 index 00000000..b06fe9ce --- /dev/null +++ b/copilot-app/6-agent-merge.md @@ -0,0 +1,64 @@ +--- +title: "Lesson 6 - Merging with Agent Merge" +description: "Open the filtering pull request, review it in My work, and let Agent Merge fix what's blocking it and merge it for you — the top rung of the merge-automation ladder." +--- + +Your filtering feature is built, verified, and seen working in a browser. The last step is to merge it. You've merged twice already in this harness — both times you opened the pull request and merged it yourself on github.com. This time you'll let the app do the heavy lifting with **Agent Merge**, which shepherds a pull request through its whole lifecycle from inside the app. + +In this lesson, you will: + +- learn what Agent Merge is and how it automates the merge lifecycle. +- enable Agent Merge on your filtering session. +- watch it create the pull request, run CI, and merge when everything is green. + +## Scenario + +Over the last few modules you've explored various levels of automation, from creating code to allowing Copilot to validate a UI directly. To further speed development, Tailspin Toys would like to see if there's a way pull requests that have been vetted and validated can automatically be merged. + +## Introducing Agent Merge + +**Agent Merge** allows automation of the last mile of landing a pull request via Copilot app. When you enable it, the app's session reads your pull request, addresses what's blocking it — fixing failing CI checks, responding to review comments, rebasing when needed — and merges it as soon as GitHub allows. It runs in the background, survives app restarts, and turns itself off once your pull request is merged. + +Up to this point you've been the one clicking **Merge pull request** on github.com. Agent Merge shifts that responsibility to the agent so you can move on to the next task while it shepherds the PR through to completion. You still review and approve the work — the agent just handles the mechanical finish line. + +## Use Agent Merge to manage the PR + +You've reviewed the code manually, ran tests, and even allowed Copilot to validate the UI. Now it's time to merge the new code into the codebase! Let's allow agent merge to shepherd the PR through continuous integration (CI) and to merge. + +1. Return to the session you had open from the previous module where you were adding filtering functionality. +2. In the upper right-hand corner, select the dropdown next to **Create PR**. +3. Select **Agent merge** to enable agent merge. + + ![The Create PR dropdown in the GitHub Copilot app expanded, with an arrow pointing to the Agent merge option](images/app-enable-agent-merge.png) + +4. The button text now changes to **Agent merge**. +5. Select the **Agent merge** button to start the agent merge process. + +Copilot app then begins the process of creating and managing the PR! It starts by exploring the project to determine how best to create a PR, followed by creating the new PR. + +After a few moments, you'll notice Copilot starts work again, looking at the PR conditions - the CI process of running all the tests on your repository. It will report back status on any reviews left by other team members, any checks that need to run (the CI process), and if the PR is mergeable. + +6. Allow agent merge to merge the pull request by selecting the dropdown next to **Agent merge** then **Merge pull request**. + + ![The Agent merge dropdown showing the agent's allowed actions — Address reviews, Fix CI failures, Resolve conflicts — with an arrow pointing to Merge pull request](images/app-agent-merge-merge.png) + +7. Once all CI processes are green (meaning the tests passed), Copilot will merge the pull request! + +## Summary and next steps + +You've automated several parts of the development process, including generating code, testing and validating code, and now the pull request process. You: + +- learned what Agent Merge is and how it automates the merge lifecycle. +- enabled Agent Merge on your filtering session. +- watched it create the pull request, run CI, and merge when everything was green. + +Next, you'll explore **canvases** — a richer way to plan and visualize work with the agent. Continue to [Lesson 7 - Planning with canvases][next-lesson]. + +## Resources + +- [Managing issues and pull requests with the GitHub Copilot app][managing-issues-prs] +- [About the GitHub Copilot app][about-copilot-app] + +[next-lesson]: 7-canvases.md +[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app diff --git a/copilot-app/7-canvases.md b/copilot-app/7-canvases.md new file mode 100644 index 00000000..525b071c --- /dev/null +++ b/copilot-app/7-canvases.md @@ -0,0 +1,124 @@ +--- +title: "Lesson 7 - Planning with canvases" +description: "Create a shared, agent-driven canvas in the GitHub Copilot app to plan and track your work alongside the agent." +--- + +So far you've directed agents through chat. But a lot of work doesn't live in a conversation — it lives on a board, in a document, or on a checklist. **Canvases** give you and the agent a shared surface for exactly that kind of work, right inside the app. In this lesson you'll create a simple canvas to plan and track the backlog you've been working through. + +In this lesson, you will: + +- understand what a canvas is and when to use one. +- create a shared Kanban board canvas to triage your backlog. +- save the canvas to your repository and merge it for the team. +- open the canvas in a new session and start work from it. + +## Scenario + +Looking at a list of issues can be rather daunting, even in the best of times. Tailspin Toys' developers have been looking for a tool that would allow them to quickly triage issues, and begin work on them in Copilot app. + +## What is a canvas? + +A [canvas][canvas-docs] is a shared, interactive surface for a work artifact — a plan, a triage board, a release checklist, a dashboard, or a document. While chat is great for describing intent and reasoning through ambiguity, most work happens on a *surface*. Canvases let you collaborate with the agent directly on that surface. + +Canvases are **bidirectional**: the agent can update the canvas while it works, and you can edit the same surface yourself. When you create a canvas, the agent builds it based on your prompt and workflow, and you can ask it to add, remove, or revise capabilities as you go. Once created, a canvas opens in the app's right side panel. + +Some common examples include: + +- **Markdown canvases** for planning your day and prioritizing issues and pull requests. +- **Agentic kanban boards** where people and agents add cards and move work across columns. +- **Issue triage boards** that summarize top issues and recurring themes for a repository. + +## Why use a canvas? + +Reach for a canvas when a task needs structure, iteration, and verification, and a chat alone isn't enough. A canvas lets you: + +- ground the agent's work in an actual artifact that fits your workflow. +- steer or correct work directly on the shared surface, then let the agent continue from your changes. +- inspect progress as visible changes to an artifact, not just chat responses. + +## Create a canvas to track your work + +You've shipped a lot: the star rating, the documentation standard, and the filtering feature are all merged. But there's still items on the backlog. Let's create the canvas to help quickly triage the work. + +1. Return to (or open) the GitHub Copilot app. +2. Select the **Home screen**. +3. Ensure `tailspin-toys` is selected for the repo. +4. In the prompt box, use the following prompt to create our canvas that meets our needs: + + ```plaintext + Create a basic Kanban board canvas that allows me to quickly triage work. Highlight the three issues which are most likely to need attention right now, with the remainder in a second section down below. The top three cards should include a description of the issue's content and a justification of why they're at the top of the list. Each issue should have a button that allows me to add it to the current context for the current session so I can get to work on it straightaway. + ``` + +Copilot will get to work on creating the canvas! + +> [!NOTE] +> This will take a few minutes for it to do so. Because this is a complicated task, you might not be satisfied with the first version. You can continue to prompt to build the tool of your dreams! + +## Save the canvas and merge it to the repository + +Canvases can become assets in the repository, just like instructions files and skills. Let's ask Copilot to add it to our repository and merge it so the whole team can use it. + +1. In the same session, ask Copilot to save the canvas to the repository by using the following prompt: + + ```plaintext + Let's save this canvas definition to the repository so I can share it with my development team + ``` + +2. Once Copilot has saved the canvas files, select the dropdown next to **Create PR** in the upper right-hand corner. +3. Select **Agent merge** to enable agent merge. + + ![The Create PR dropdown in the GitHub Copilot app expanded, with an arrow pointing to the Agent merge option](images/app-enable-agent-merge.png) + +4. The button text now changes to **Agent merge**. +5. Select the **Agent merge** button to start the agent merge process. + +Copilot app begins the process of creating and managing the PR. It starts by exploring the project to determine how best to create a PR, then creates it. + +After a few moments, you'll notice Copilot starts work again, looking at the PR conditions — the CI process of running all the tests on your repository. It will report back status on any reviews left by other team members, any checks that need to run (the CI process), and if the PR is mergeable. + +6. Allow agent merge to merge the pull request by selecting the dropdown next to **Agent merge** then **Merge pull request**. + + ![The Agent merge dropdown showing the agent's allowed actions — Address reviews, Fix CI failures, Resolve conflicts — with an arrow pointing to Merge pull request](images/app-agent-merge-merge.png) + +7. Wait for all CI processes to pass (go green). Once they do, Copilot will merge the pull request automatically! + +You've now created a new shared canvas for your team! + +## Work in the canvas + +With the canvas created, let's start a new session and put it to work! + +1. Inside the Copilot app, start a new session by selecting **New session** next to **tailspin-toys**. +2. Ask Copilot to open the triage canvas by using the following prompt: + + ```plaintext + Open the triage issues canvas + ``` + +3. You should notice the canvas you built is now open in this new session! +4. Select **Add to current context** on one of the issues that's of most interest to you. +5. Copilot gets to work on the issue! + +You've now used a canvas you created to streamline the development process. + +## Summary and next steps + +You created a shared surface where you and the agent can collaborate! You: + +- learned what canvases are and when to use them. +- created a shared Kanban triage board canvas with the agent. +- saved and merged the canvas to your repository with Agent Merge. +- opened the canvas in a new session and used it to start work. + +With your backlog tracked, take a step back to review everything you've built and where to go next. Continue to [Lesson 8 - Review and next steps][next-lesson]. + +## Resources + +- [Working with canvas extensions in the GitHub Copilot app][canvas-docs] +- [Canvases on Awesome Copilot][awesome-copilot-canvases] +- [About the GitHub Copilot app][about-copilot-app] + +[next-lesson]: 8-review.md +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[awesome-copilot-canvases]: https://awesome-copilot.github.com/canvases +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app diff --git a/copilot-app/8-review.md b/copilot-app/8-review.md new file mode 100644 index 00000000..1f5dcba8 --- /dev/null +++ b/copilot-app/8-review.md @@ -0,0 +1,83 @@ +--- +title: "Lesson 8 - Review and next steps" +description: "Recap the GitHub Copilot app harness, automate recurring work, and explore where to go next." +--- + +Over the last several lessons, you took a feature from idea to merge with the GitHub Copilot app, including: + +- connecting a repository and orienting to the app's workspace and your seeded backlog. +- starting sessions from a direct task and from issues, and using Plan and Autopilot modes to control how the agent works. +- guiding the agent with custom instructions and a reusable skill. +- testing your work with the Playwright MCP server in a real browser. +- collaborating with the agent on a shared canvas. +- shipping changes up a ladder of merge automation — from merging on github.com yourself to letting **Agent Merge** land a pull request. + +Let's automate some recurring work, talk through best practices, and look at where to go next. + +## Automate recurring work + +The app can run agents for you on a schedule or on demand through **automations** — great for routine tasks like triaging new issues or recapping recent activity. Let's create a simple, non-destructive one. + +1. Select **Automations** in the sidebar, then select **New automation**. +2. Give it a name, such as `Recap my recent work`. +3. Choose a trigger. **Manual** lets you run it on demand; **On a schedule** runs it automatically; **When an issue is created** reacts to new issues. Choose **Manual** for this lesson. +4. Enter a read-only prompt so the automation can't change anything, for example: + + ```plaintext + Summarize the pull requests merged in this repository over the last week, and list any issues still open in the backlog. + ``` + +5. Pick the project (your Tailspin Toys repository) and create the automation. + + ![The New automation dialog showing the name, trigger options, the Run in the cloud toggle, the tools dropdown, and the prompt field](images/app-automation-dialog.png) + +6. Run it on demand to see the result. + +> [!TIP] +> Automations can run locally or in the cloud. Enable **Run in the cloud** and pick the **Tools** an automation may use when you want it to run unattended on a schedule. Keep scheduled automations scoped and non-destructive until you trust their output. + +## Best practices + +When using any AI tool, the infrastructure around it drives the quality of what you get out. Instructions files, skills, and custom agents all played a part in this workshop — invest in them and reuse them across sessions. + +Match the **mode and model** to the task. Use **Plan** to think through an approach before building, **Interactive** to stay in the loop on focused changes, and **Autopilot** only for well-scoped, isolated tasks. Choose a faster model for routine edits and a more capable model with higher reasoning effort for complex work. + +Context still matters as much as infrastructure. Clearly describing *what* you want built, *why*, and *how* meaningfully changes the output. Quick chats are a great place to scope an idea before you commit it to a full session. + +## More to explore + +You've covered the core workflow. A few more features worth a look: + +- **Quick chats** for fast, throwaway questions that don't need a full session. +- **Rubber duck** to talk through a problem and get high-signal feedback before you build. +- [**Custom agents**][custom-agents] to package a role, its tools, and its instructions for repeatable, specialized work. +- [`/chronicle`][chronicle] to generate a narrative of what happened in a session. +- [Bring your own key (BYOK)][byok] to use models from your own provider. +- [Cloud sandboxes][sandboxes] to run sessions in a GitHub-hosted isolated environment. +- [Deep links][deep-links] to open the app straight into a repository, session, or prompt. + +## Next steps + +The best way to improve with any tool is to keep using it! Use it for production code, for hobby code, for the little app you've had in mind for years but never got around to building. Share your learnings with your team, and learn from theirs. And, as always, explore the documentation. + +If you'd like to explore more of the GitHub Copilot ecosystem, check out the [VS Code harness](https://github-samples.github.io/agents-in-sdlc/vscode/), the [Copilot CLI harness](https://github-samples.github.io/agents-in-sdlc/cli/), or the [Cloud agent harness](https://github-samples.github.io/agents-in-sdlc/cloud/). + +## Resources + +- [About the GitHub Copilot app][about-copilot-app] +- [Getting started with the GitHub Copilot app][getting-started] +- [Customize the GitHub Copilot app][customize] +- [Using automations][using-automations] +- [Working with canvas extensions][canvas-docs] +- [About cloud and local sandboxes][sandboxes] + +[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app +[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started +[customize]: https://docs.github.com/copilot/how-tos/github-copilot-app/customize-github-copilot-app +[using-automations]: https://docs.github.com/copilot/how-tos/github-copilot-app/using-automations +[canvas-docs]: https://docs.github.com/copilot/how-tos/github-copilot-app/working-with-canvas-extensions +[sandboxes]: https://docs.github.com/copilot/concepts/about-cloud-and-local-sandboxes +[chronicle]: https://docs.github.com/copilot/how-tos/copilot-cli/use-copilot-cli/chronicle +[custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents +[byok]: https://docs.github.com/copilot/how-tos/github-copilot-app/use-byok-models +[deep-links]: https://docs.github.com/copilot/how-tos/github-copilot-app/open-with-deep-links diff --git a/copilot-app/README.md b/copilot-app/README.md new file mode 100644 index 00000000..22d6dbb3 --- /dev/null +++ b/copilot-app/README.md @@ -0,0 +1,54 @@ +--- +title: "GitHub Copilot app" +--- + +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, CI fixes, and merge. + +Across these lessons you'll install the app and set up your project, then get oriented in the app's workspace and the backlog the template seeded for you. You'll start with a small change — adding a star rating — then add a custom instructions standard from an issue, build a filtering feature in an isolated agent session, and verify it with a reusable skill. You'll add the Playwright MCP server to explore the feature in a real browser, then climb a ladder of merge automation that ends with **Agent Merge** landing your pull request. Finally you'll collaborate on a shared canvas and automate recurring work — a complete loop from idea to merged feature. + +## Lessons + +| Lesson | Topic | Description | +|--------|-------|-------------| +| [0. Prerequisites][ex0] | Setup | Install Node.js and create your copy of the Tailspin Toys project | +| [1. Install the Copilot app][ex1] | Setup | Install the app, connect your project, and get oriented in the workspace | +| [2. Running your first agent session][ex2] | First change | Start a session and ship a small change as your first pull request | +| [3. Guiding Copilot with custom instructions][ex3] | Context | Add a documentation standard from an issue and merge it | +| [4. Building a feature with Autopilot][ex4] | Core Feature | Use Plan and Autopilot to build filtering, then verify it with a skill | +| [5. Testing with Playwright MCP][ex5] | External Tools | Add the Playwright MCP server and explore your feature in a browser | +| [6. Merging with Agent Merge][ex6] | Merge | Let Agent Merge fix and land your filtering pull request | +| [7. Planning with canvases][ex7] | Collaboration | Create a shared canvas to plan and track your work | +| [8. Review and next steps][ex8] | Summary | Automate recurring tasks and explore what's next | + +## Prerequisites + +Before attending this workshop, please ensure you have: + +- [ ] A GitHub account with an active **Copilot Student, Pro, Pro+, Business, or Enterprise** plan +- [ ] A computer running **macOS, Linux, or Windows** +- [ ] [Git installed][install-git] on your computer + +> [!TIP] +> No paid plan? Verified students can get GitHub Copilot for free through [GitHub Education][callout-student-plan-education]. The **Copilot Student** plan includes the agent, MCP, code review, and Copilot CLI features this workshop uses — so you can complete every harness with it. + +> [!NOTE] +> Because the Copilot app runs on your own machine rather than in a codespace, [Lesson 0][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. + +## Get Started + +**[Start with Lesson 0: Prerequisites →][ex0]** + +[ex0]: 0-prerequisites.md +[ex1]: 1-install-copilot-app.md +[ex2]: 2-add-star-rating.md +[ex3]: 3-custom-instructions.md +[ex4]: 4-build-filtering.md +[ex5]: 5-mcp-playwright.md +[ex6]: 6-agent-merge.md +[ex7]: 7-canvases.md +[ex8]: 8-review.md +[install-git]: https://github.com/git-guides/install-git +[callout-student-plan-education]: https://github.com/education/students diff --git a/copilot-app/images/app-0-create-repository.png b/copilot-app/images/app-0-create-repository.png new file mode 100644 index 00000000..34913187 Binary files /dev/null and b/copilot-app/images/app-0-create-repository.png differ diff --git a/copilot-app/images/app-0-use-template.png b/copilot-app/images/app-0-use-template.png new file mode 100644 index 00000000..cf02650d Binary files /dev/null and b/copilot-app/images/app-0-use-template.png differ diff --git a/copilot-app/images/app-2-review-panel.png b/copilot-app/images/app-2-review-panel.png new file mode 100644 index 00000000..95006ea5 Binary files /dev/null and b/copilot-app/images/app-2-review-panel.png differ diff --git a/copilot-app/images/app-2-start-session.png b/copilot-app/images/app-2-start-session.png new file mode 100644 index 00000000..b06d71ec Binary files /dev/null and b/copilot-app/images/app-2-start-session.png differ diff --git a/copilot-app/images/app-4-plan-mode.png b/copilot-app/images/app-4-plan-mode.png new file mode 100644 index 00000000..1eaea46f Binary files /dev/null and b/copilot-app/images/app-4-plan-mode.png differ diff --git a/copilot-app/images/app-agent-merge-merge.png b/copilot-app/images/app-agent-merge-merge.png new file mode 100644 index 00000000..03ec3689 Binary files /dev/null and b/copilot-app/images/app-agent-merge-merge.png differ diff --git a/copilot-app/images/app-automation-dialog.png b/copilot-app/images/app-automation-dialog.png new file mode 100644 index 00000000..1ba60bf1 Binary files /dev/null and b/copilot-app/images/app-automation-dialog.png differ diff --git a/copilot-app/images/app-enable-agent-merge.png b/copilot-app/images/app-enable-agent-merge.png new file mode 100644 index 00000000..47462d47 Binary files /dev/null and b/copilot-app/images/app-enable-agent-merge.png differ diff --git a/copilot-app/images/app-new-session-from-issue.png b/copilot-app/images/app-new-session-from-issue.png new file mode 100644 index 00000000..26db5be2 Binary files /dev/null and b/copilot-app/images/app-new-session-from-issue.png differ diff --git a/copilot-app/images/app-open-terminal.png b/copilot-app/images/app-open-terminal.png new file mode 100644 index 00000000..dbdcdb01 Binary files /dev/null and b/copilot-app/images/app-open-terminal.png differ diff --git a/copilot-app/images/app-select-changes.png b/copilot-app/images/app-select-changes.png new file mode 100644 index 00000000..ebfc5c94 Binary files /dev/null and b/copilot-app/images/app-select-changes.png differ