Skip to content

Commit 3ccacf8

Browse files
GeekTrainerCopilot
GeekTrainer
and
Copilot
committed
docs: add Copilot App workshop content as pure markdown
Add the GitHub Copilot app harness lessons as a standalone, github.com- readable markdown set under copilot-app/. Converted from the Starlight MDX source: kept frontmatter, rewrote internal lesson links to relative .md, repointed images to copilot-app/images/, and pointed cross-harness links at the published site. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 5a561ae commit 3ccacf8

21 files changed

Lines changed: 1051 additions & 0 deletions

‎copilot-app/0-prerequisites.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
---
2+
title: "Lesson 0 - Prerequisites"
3+
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."
4+
---
5+
6+
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.
7+
8+
In this lesson, you will:
9+
10+
- install Node.js so the project's tests can run on your machine.
11+
- create your own copy of the Tailspin Toys project from the template.
12+
13+
## Install Node.js
14+
15+
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.
16+
17+
The simplest option on every platform is the official installer:
18+
19+
1. In your operating system, open a terminal window using Windows Terminal, macOS terminal, or whatever you typically use.
20+
2. Run the following command to confirm you have at least Node.js 22 or higher installed:
21+
22+
```shell
23+
node --version
24+
```
25+
26+
3. If you see `v22` or a higher number, you can skip to the next section!
27+
28+
> [!TIP]
29+
> You only need to complete these steps if you don't have Node installed, or you need to update.
30+
31+
4. Open the [Node.js download page][node-download].
32+
5. Download the **LTS** build for your operating system.
33+
6. Run the installer and accept the defaults. On Windows, keep the **Add to PATH** option selected.
34+
7. Once installed, open a new terminal window.
35+
8. Confirm the install in the new terminal window by running the following:
36+
37+
```bash
38+
node --version
39+
```
40+
41+
9. You should see `v22.x.x` or higher.
42+
43+
> [!TIP]
44+
> 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.
45+
46+
## Set up the lab repository
47+
48+
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.
49+
50+
1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/tailspin-toys`.
51+
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**.
52+
53+
![The Use this template button with Create a new repository selected from the dropdown](images/app-0-use-template.png)
54+
55+
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.
56+
57+
![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)
58+
59+
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.
60+
61+
> [!NOTE]
62+
> 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.
63+
64+
## Summary and next steps
65+
66+
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.
67+
68+
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].
69+
70+
## Resources
71+
72+
- [Download Node.js][node-download]
73+
- [Creating a repository from a template][template-repository]
74+
- [About the GitHub Copilot app][about-copilot-app]
75+
76+
[next-lesson]: 1-install-copilot-app.md
77+
[nodejs]: https://nodejs.org/
78+
[node-download]: https://nodejs.org/en/download
79+
[docker]: https://www.docker.com/products/docker-desktop/
80+
[dev-containers]: https://code.visualstudio.com/docs/devcontainers/containers
81+
[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository
82+
[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app

‎copilot-app/1-install-copilot-app.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
title: "Lesson 1 - Installing the GitHub Copilot app"
3+
description: "Install the GitHub Copilot app, connect the repository you created from the template, get oriented in the workspace, and try a quick chat."
4+
---
5+
6+
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.
7+
8+
In this lesson, you will:
9+
10+
- install the GitHub Copilot app and sign in.
11+
- add your project to the app from its GitHub repository.
12+
- get oriented in the workspace, including the backlog the template seeded for you.
13+
- try a quick chat to learn about the app itself.
14+
15+
## Scenario
16+
17+
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.
18+
19+
> [!NOTE]
20+
> 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.
21+
22+
## Install and configure the GitHub Copilot app
23+
24+
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 select add our Tailspin Toys repo to the app.
25+
26+
1. In a browser, open the [landing page for the GitHub Copilot app][download-app].
27+
2. Download the app for your platform and install it following the instructions provided on the landing page.
28+
3. Open the app once it's installed.
29+
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.
30+
5. After authenticating, you'll be asked about connecting your repositories. Select the Tailspin Toys repo you just created, which should be named `<YOUR_GITHUB_HANDLE>/tailspin-toys`.
31+
6. Select **Continue** to continue the onboarding.
32+
7. When prompted for a theme, select the one which brings you the most joy, then select **Finish**.
33+
34+
> [!NOTE]
35+
> 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 (\<YOUR_GITHUB_HANDLE\>/tailspin-toys), then select it. Your repo will now be added to the Copilot app!
36+
37+
## Get oriented in the workspace
38+
39+
With your project connected, take a moment to learn your way around. The app organizes everything into a few areas in the sidebar:
40+
41+
- **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.
42+
- **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.
43+
- **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.
44+
- **Automations** — saved agent tasks that run on a schedule or on demand. You'll create one near the end of the harness.
45+
46+
### Find your seeded backlog
47+
48+
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.
49+
50+
1. Select **My work** in the sidebar.
51+
2. Confirm you see the three issues the template seeded for your backlog:
52+
53+
- Allow users to filter games by category and publisher
54+
- Add a custom instructions standard so generated TypeScript code includes clear TSDoc doc comments
55+
- Stretch Goal: Implement pagination on the game list page
56+
57+
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.
58+
59+
> [!NOTE]
60+
> 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!
61+
62+
## Try a quick chat
63+
64+
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.
65+
66+
1. In the sidebar, select **+** next to **Quick chats** to open a new chat.
67+
2. Ask the app how its own sessions work:
68+
69+
```plaintext
70+
How does the GitHub Copilot app use worktrees?
71+
```
72+
73+
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.
74+
75+
## Summary and next steps
76+
77+
Congratulations! You've installed the GitHub Copilot app, connected your project, and explored your workspace. You learned how to:
78+
79+
- install the app and sign in to GitHub.
80+
- add a project from its GitHub repository.
81+
- get oriented in the workspace and find your seeded backlog in **My work**.
82+
- use a quick chat to ask a fast, throwaway question.
83+
84+
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].
85+
86+
## Resources
87+
88+
- [About the GitHub Copilot app][about-copilot-app]
89+
- [Getting started with the GitHub Copilot app][getting-started]
90+
- [Working with agent sessions in the GitHub Copilot app][agent-sessions]
91+
92+
[ex0]: 0-prerequisites.md
93+
[next-lesson]: 2-add-star-rating.md
94+
[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app
95+
[getting-started]: https://docs.github.com/copilot/how-tos/github-copilot-app/getting-started
96+
[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions
97+
[download-app]: https://gh.io/app

‎copilot-app/2-add-star-rating.md‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
title: "Lesson 2 - Running your first agent session"
3+
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."
4+
---
5+
6+
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.
7+
8+
In this lesson, you will:
9+
10+
- start an agent session and learn how a session is structured.
11+
- ask the agent to make a small, focused change to the project.
12+
- review the change in the workspace diff view.
13+
- run the app locally to confirm the change in the browser.
14+
- open and merge your first pull request.
15+
16+
## Scenario
17+
18+
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.
19+
20+
## Anatomy of a session
21+
22+
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.
23+
24+
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.
25+
26+
## Start a session and request our change
27+
28+
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.
29+
30+
1. Return to (or open) the GitHub Copilot app.
31+
2. Select the **Home screen**.
32+
3. Ensure `tailspin-toys` is selected for the repo.
33+
34+
![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)
35+
36+
4. Use the following prompt to request the change:
37+
38+
```plaintext
39+
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.
40+
```
41+
42+
> [!NOTE]
43+
> 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.
44+
45+
5. Select <kbd>Enter</kbd> to send the prompt to Copilot.
46+
47+
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!
48+
49+
## Review the diff
50+
51+
All AI-generated changes deserve a review before they're merged, even small ones. Let's explore the changes, right here in Copilot app.
52+
53+
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.
54+
55+
![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)
56+
57+
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`:
58+
59+
```astro
60+
{game.starRating !== null ? (
61+
<span class="text-xs font-medium px-2.5 py-0.5 rounded bg-amber-900/60 text-amber-300" data-testid="game-rating">
62+
★ {game.starRating} / 5
63+
</span>
64+
) : (
65+
<span class="text-xs font-medium text-slate-500" data-testid="game-rating-empty">
66+
No rating yet
67+
</span>
68+
)}
69+
```
70+
71+
> [!NOTE]
72+
> 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.
73+
74+
## Check the changes
75+
76+
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!
77+
78+
1. In the upper right hand corner of the Copilot app, select **Open** next to the terminal icon.
79+
80+
![The GitHub Copilot app top toolbar with an arrow pointing to the Open button next to the terminal icon](images/app-open-terminal.png)
81+
82+
2. Enter the following command in the terminal window to start the web app's dev server:
83+
84+
```shell
85+
npm run dev
86+
```
87+
88+
3. Once the server starts (this will just take a moment), open a browser window.
89+
4. Navigate to http://localhost:4321.
90+
5. You should now see star ratings on all the games on the landing page!
91+
6. Return to the terminal window.
92+
7. Select <kbd>Ctl</kbd>+<kbd>C</kbd> to stop the dev server.
93+
94+
## Open and merge your first pull request
95+
96+
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.
97+
98+
1. In the upper right hand corner, select **Create PR**.
99+
2. If prompted, select **Sign in with your browser** and follow the prompts to authenticate.
100+
3. Copilot gets to work on creating the PR.
101+
102+
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!
103+
104+
4. Select **Ready to merge**.
105+
5. Select **Merge pull request** on the new dialog window the merge your pull request!
106+
107+
You've now pushed a new feature to the website!
108+
109+
## Summary and next steps
110+
111+
You've started your first agent session and shipped your first change! Specifically, you:
112+
113+
- started an agent session and learned how sessions are structured.
114+
- directed the agent to make a small, focused change to the game cards.
115+
- reviewed the change in the workspace diff view.
116+
- ran the app locally to confirm the star rating in the browser.
117+
- opened a pull request and merged it yourself on github.com.
118+
119+
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].
120+
121+
## Resources
122+
123+
- [Working with agent sessions in the GitHub Copilot app][agent-sessions]
124+
- [About the GitHub Copilot app][about-copilot-app]
125+
- [Managing issues and pull requests with the GitHub Copilot app][managing-issues-prs]
126+
127+
[prior-lesson]: 1-install-copilot-app.md#install-and-configure-the-github-copilot-app
128+
[next-lesson]: 3-custom-instructions.md
129+
[agent-sessions]: https://docs.github.com/copilot/how-tos/github-copilot-app/agent-sessions
130+
[about-copilot-app]: https://docs.github.com/copilot/concepts/agents/github-copilot-app
131+
[managing-issues-prs]: https://docs.github.com/copilot/how-tos/github-copilot-app/managing-issues-and-pull-requests

0 commit comments

Comments
 (0)