Skip to content

Commit 1235115

Browse files
GeekTrainerCopilot
GeekTrainer
and
Copilot
committed
Restructure Using-GitHub-Copilot-Coding-Agent into section files
Split the single large README.md into a landing page with TOC and 4 focused section files. Reordered Custom Instructions before Code Review since Copilot Code Review leverages instructions. - 1-Assigning-and-Tracking.md: Assign tasks + track/steer sessions - 2-Instructions-and-Review.md: Custom instructions (moved up) + PR review - 3-Advanced-Customization.md: Custom agents, MCP, hooks, memory - 4-Security-and-SDLC.md: Security, CLI/Raycast integration, model selection Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 7095f09 commit 1235115

File tree

5 files changed

+528
-477
lines changed

5 files changed

+528
-477
lines changed

‎Using-GitHub-Copilot-Coding-Agent/1-Assigning-and-Tracking.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
[← Back to Module Overview](README.md) | [Next: Custom Instructions and Code Review →](2-Instructions-and-Review.md)
2+
3+
# Assigning Tasks and Tracking Agent Sessions
4+
5+
## 🗒️ Part 1: Assigning Tasks to GitHub Copilot Coding Agent
6+
7+
### 🎯 Learning Goals
8+
9+
- Understand how the coding agent differs from IDE agent mode.
10+
- Assign a GitHub Issue to Copilot coding agent.
11+
- Trigger Copilot coding agent from multiple surfaces: issues, pull request comments, and the agents panel.
12+
13+
### What is the Copilot Coding Agent?
14+
15+
The **GitHub Copilot coding agent** works autonomously in the background using a GitHub Actions-powered ephemeral development environment. When you give it a task, it:
16+
17+
1. Reads your codebase and issue context.
18+
2. Creates a `copilot/` branch.
19+
3. Writes code, runs your tests and linters, and iterates on errors.
20+
4. Opens a pull request and requests your review.
21+
22+
This is distinct from **agent mode in your IDE**, which edits your local files interactively. The coding agent is fully asynchronous — you can close your laptop while it works.
23+
24+
### Exercise 1A: Assign an Issue to Copilot
25+
26+
1. Navigate to your repository's **Issues** tab on GitHub.com.
27+
2. Create a new issue with a clear, well-scoped description. For example:
28+
29+
```
30+
Title: Add the ability to delete a recipe
31+
32+
Description:
33+
Users should be able to delete a recipe from the recipe list.
34+
- Add a DELETE /recipes/:id endpoint in src/routes.js
35+
- Remove the recipe row from the SQLite database
36+
- Add a "Delete" button to the recipe detail view
37+
- Write a test that confirms a deleted recipe returns 404
38+
```
39+
40+
3. On the issue page, click **Assignees** and select **Copilot** from the assignee list.
41+
42+
> Copilot will begin working immediately. You'll see the issue label update to indicate an agent session is in progress.
43+
44+
4. Observe that Copilot creates a new branch named `copilot/<issue-number>-<slug>` and begins opening commits.
45+
46+
### Exercise 1B: Trigger Copilot from a Pull Request Comment
47+
48+
You can also invoke the coding agent on an *existing pull request* by mentioning `@copilot` in a PR comment.
49+
50+
1. Open any open pull request in your repository.
51+
2. In a comment, type a specific request, for example:
52+
53+
```
54+
@copilot Please add input validation to the recipe creation form
55+
and return a 400 status code with an error message if the title field is empty.
56+
```
57+
58+
3. Copilot will respond in the PR thread, then push additional commits to address your request.
59+
60+
### Exercise 1C: Trigger Copilot from the Agents Panel
61+
62+
The **agents panel** is available on every page on GitHub.com.
63+
64+
1. Click the agent icon (looks like a hexagon/robot) in the top navigation bar on any GitHub page.
65+
2. Click **New task**.
66+
3. Select your repository and describe the work you want done.
67+
4. Submit the task. Copilot will open a new pull request with the changes.
68+
69+
In the above exercises we achieved the following:
70+
- ✅ Assigned a GitHub issue to the coding agent
71+
- ✅ Invoked the agent via a PR comment using `@copilot`
72+
- ✅ Started a new coding agent task from the agents panel
73+
74+
---
75+
76+
## 🗒️ Part 2: Tracking and Steering Agent Sessions
77+
78+
### 🎯 Learning Goals
79+
80+
- Track the progress of Copilot's work across multiple surfaces.
81+
- Read and interpret session logs.
82+
- Steer Copilot mid-session when you want to redirect its approach.
83+
- Stop a session that has gone off-track.
84+
85+
### The Agents Tab
86+
87+
1. Open the [agents tab](https://github.com/copilot/agents) by clicking the agent icon in the GitHub navigation bar, then selecting **View all**.
88+
2. You'll see a list of all your running and past agent sessions.
89+
3. Click on a session to open the **session log and overview**, which shows:
90+
- Session status (running, completed, stopped)
91+
- Token usage and session duration
92+
- A step-by-step internal log showing how Copilot approached your task
93+
94+
### Reading Session Logs
95+
96+
Session logs show Copilot's internal reasoning and tool usage. You can see:
97+
98+
- Which files Copilot read to understand the codebase.
99+
- What commands it ran (e.g., test runners, linters).
100+
- How it iterated to fix errors before pushing.
101+
- Which security checks it performed (CodeQL, secret scanning, dependency vulnerability checks).
102+
103+
> **Tip:** Session logs are also accessible from Visual Studio Code via the GitHub Pull Requests extension. Click on a pull request in the Copilot sessions list, then click **View Session**.
104+
105+
### Exercise 2A: Steer a Running Session
106+
107+
While Copilot is working, you can give it additional guidance from the agents tab:
108+
109+
1. Open the [agents tab](https://github.com/copilot/agents) and select an **in-progress** session.
110+
2. Type a steering message in the prompt box, for example:
111+
112+
```
113+
Use our existing ErrorHandler utility instead of writing custom
114+
try-catch blocks for the new endpoints.
115+
```
116+
117+
3. Submit the message. Copilot will incorporate your guidance after finishing its current tool call.
118+
119+
> **Note:** Steering consumes one premium request per message.
120+
121+
### Exercise 2B: Stop a Session
122+
123+
If Copilot is going in a wrong direction or you have changed your mind about a task:
124+
125+
1. Open the session log viewer from the agents tab.
126+
2. Click **Stop session**.
127+
128+
The agent stops immediately. The branch and any commits made so far are preserved, so you can inspect them.
129+
130+
### Tracking Across Other Surfaces
131+
132+
| Surface | How to access |
133+
|---|---|
134+
| **GitHub CLI** | `gh agent-task list` / `gh agent-task view --repo owner/repo <pr-number>` (requires CLI v2.80.0+) |
135+
| **VS Code** | GitHub Pull Requests extension → Copilot sessions list in the sidebar |
136+
| **JetBrains IDEs** | GitHub Copilot Chat extension → **GitHub Coding Agent Jobs** button (public preview) |
137+
| **Eclipse** | GitHub Copilot Chat extension → agent icon in chat window (public preview) |
138+
| **GitHub Mobile** | Home page → Agents section → **Agent Tasks** |
139+
| **Raycast** | GitHub Copilot extension for Raycast → **View Tasks** command |
140+
141+
In the above exercises we achieved the following:
142+
- ✅ Navigated the agents tab to track sessions
143+
- ✅ Read and interpreted a Copilot session log
144+
- ✅ Steered a running session with additional guidance
145+
- ✅ Stopped an off-track session
146+
147+
---
148+
149+
[← Back to Module Overview](README.md) | [Next: Custom Instructions and Code Review →](2-Instructions-and-Review.md)

‎Using-GitHub-Copilot-Coding-Agent/2-Instructions-and-Review.md‎

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
[← Previous: Assigning and Tracking](1-Assigning-and-Tracking.md) | [Next: Advanced Customization →](3-Advanced-Customization.md)
2+
3+
# Custom Instructions and Code Review
4+
5+
## 🗒️ Part 1: Custom Instructions
6+
7+
### 🎯 Learning Goals
8+
9+
- Write custom repository instructions to guide Copilot's behavior.
10+
- Understand how instructions improve both the coding agent and Copilot code review.
11+
12+
### Writing Custom Instructions
13+
14+
Custom instructions are Markdown files you store in your repository that tell Copilot about your preferences, conventions, and architecture — so you don't have to repeat yourself in every task.
15+
16+
1. Create the file `.github/copilot-instructions.md` in your repository.
17+
2. Add content like the following:
18+
19+
```markdown
20+
# Project Guidelines
21+
22+
## Technology Stack
23+
- Node.js with Express
24+
- SQLite via better-sqlite3
25+
- EJS templates for server-rendered HTML
26+
- xUnit-style tests with Jest
27+
28+
## Code Style
29+
- Use async/await — never raw callbacks or `.then()` chains
30+
- Follow the existing error handling pattern in `src/errorHandler.js`
31+
- All new routes must be added to `src/routes.js` following the existing pattern
32+
- Use 2-space indentation
33+
34+
## Testing
35+
- Every new route must have a corresponding test in `tests/`
36+
- Use supertest for HTTP integration tests
37+
38+
## Security
39+
- Never log user-provided input directly
40+
- Validate all request parameters before database access
41+
```
42+
43+
3. Commit the file. All subsequent Copilot coding agent sessions in this repository will now follow these instructions automatically.
44+
45+
> **Tip:** You can also define custom instructions at the organization level from your organization's settings.
46+
47+
In the above exercise we achieved the following:
48+
- ✅ Created repository custom instructions that guide both the coding agent and Copilot code review
49+
50+
---
51+
52+
## 🗒️ Part 2: Reviewing and Iterating on Copilot Pull Requests
53+
54+
### 🎯 Learning Goals
55+
56+
- Review a pull request opened by Copilot coding agent.
57+
- Leave iterative feedback to refine Copilot's solution.
58+
- Request a Copilot automated code review on your own pull requests.
59+
- Understand the governance model around Copilot PRs.
60+
61+
### Exercise 2A: Review a Copilot-Generated Pull Request
62+
63+
When Copilot finishes a task, it opens a pull request and requests your review.
64+
65+
1. Navigate to the **Pull Requests** tab in your repository.
66+
2. Open the pull request created by Copilot (marked with the Copilot author badge).
67+
3. Review the changes. The PR description will include:
68+
- A summary of what was changed and why.
69+
- References back to the original issue.
70+
- Any security scan results from the automated validation.
71+
72+
4. Leave a review comment requesting a change. For example:
73+
74+
```
75+
The delete confirmation modal is a good start, but please also add
76+
an accessible aria-label to the confirmation button.
77+
```
78+
79+
5. Submit your review. Copilot will pick up your feedback, push new commits to the same branch, and re-request your review.
80+
81+
> **Governance note:** The user who asked Copilot to create a pull request **cannot approve that same pull request**. This enforces independent review. Copilot also cannot mark its own PRs as "Ready for review" or merge them.
82+
83+
### Exercise 2B: Request a Copilot Code Review on Your Own PR
84+
85+
Copilot can also serve as a first-pass reviewer on *your* pull requests before a human review. The custom instructions you created in Part 1 will guide Copilot's review — it will check your code against the conventions and patterns you defined.
86+
87+
1. Open a pull request you've authored.
88+
2. In the **Reviewers** panel on the right side of the PR, click the gear icon.
89+
3. Select **Copilot** from the reviewer list.
90+
4. Within seconds, Copilot will leave inline comments on the diff, pointing out bugs, inefficiencies, and improvements.
91+
5. Apply or dismiss each suggestion using the inline comment controls.
92+
93+
In the above exercises we achieved the following:
94+
- ✅ Reviewed and gave iterative feedback on a Copilot-authored PR
95+
- ✅ Used Copilot as an automated code reviewer on a human-authored PR
96+
97+
---
98+
99+
[← Previous: Assigning and Tracking](1-Assigning-and-Tracking.md) | [Next: Advanced Customization →](3-Advanced-Customization.md)

‎Using-GitHub-Copilot-Coding-Agent/3-Advanced-Customization.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
[← Previous: Instructions and Review](2-Instructions-and-Review.md) | [Next: Security and SDLC →](4-Security-and-SDLC.md)
2+
3+
# Advanced Customization
4+
5+
## 🎯 Learning Goals
6+
7+
- Create a custom agent profile for a specialized coding persona.
8+
- Extend the agent with MCP servers for additional data sources and tools.
9+
- Add hooks to execute custom shell commands during agent execution.
10+
- Understand Copilot Memory (public preview).
11+
12+
---
13+
14+
## 🗒️ Part 1: Custom Agents
15+
16+
**Custom agents** are specialized versions of Copilot you define once using a Markdown file. Each profile encodes a specific persona, set of tools, and behavior. Custom agent profiles can also be defined at the [organization level](https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) in a `.github-private` repository, making them available across all repositories in your organization.
17+
18+
1. Create the file `.github/agents/documentation-agent.md`:
19+
20+
```markdown
21+
---
22+
name: documentation-agent
23+
description: Specialist for maintaining and improving project documentation
24+
---
25+
26+
You are a technical documentation specialist. Your scope is limited to
27+
documentation files only — README.md, docs/, and inline code comments.
28+
Do not modify source code logic.
29+
30+
Follow these guidelines:
31+
- Structure READMEs with: Overview, Installation, Usage, API Reference, Contributing
32+
- Use clear, concise language targeted at developers unfamiliar with the project
33+
- Add code examples for every API endpoint documented
34+
- Use relative links for internal files
35+
- Add alt text to all images
36+
- Ensure all headings are in sentence case
37+
```
38+
39+
2. Create a second agent profile `.github/agents/test-agent.md`:
40+
41+
```markdown
42+
---
43+
name: test-agent
44+
description: Specialist for writing comprehensive test coverage using Jest
45+
---
46+
47+
You are a testing specialist focused exclusively on writing and improving tests.
48+
Do not modify application source code — only test files.
49+
50+
Guidelines:
51+
- Use Jest with supertest for HTTP route tests
52+
- Write both happy-path and error-path tests for every function
53+
- Aim for 80%+ line coverage on any file you touch
54+
- Use descriptive test names that explain the scenario being tested
55+
- Mock external dependencies using jest.mock()
56+
```
57+
58+
3. Commit both files. When you assign a task from the agents panel or an issue, you can now select a specific custom agent to use.
59+
60+
---
61+
62+
## 🗒️ Part 2: Model Context Protocol (MCP) Servers
63+
64+
**MCP servers** give Copilot coding agent access to external data sources and tools — such as a project management system, internal documentation, or a database — that it wouldn't be able to reach otherwise. For organization-level or enterprise-level custom agents, the agent definition is managed centrally (not just in a repo under `.github/agents/`).
65+
66+
In those centrally managed agent profiles, you can define MCP servers directly in the YAML frontmatter of the agent profile. This allows administrators to centrally define which external tools the agent can access, eliminating the need for developers to configure MCP servers locally. This gives the agent access to those tools, allowing them to be policy-controlled and centralizing governance.
67+
68+
1. Create the file `.github/mcp.json` in your repository:
69+
70+
```json
71+
{
72+
"mcpServers": {
73+
"github": {
74+
"type": "github",
75+
"tools": ["list_issues", "search_code", "get_pull_request"]
76+
}
77+
}
78+
}
79+
```
80+
81+
2. The default GitHub MCP server is pre-configured and gives the agent access to your repository's issues, historic pull requests, and code search — grounding its responses in real project context.
82+
83+
3. To add a third-party MCP server (for example: a Jira integration, an Azure DevOps integration, or other 3rd party service), follow the [MCP integration guide](https://docs.github.com/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp) and add the server configuration to `.github/mcp.json`.
84+
85+
---
86+
87+
## 🗒️ Part 3: Hooks — Lifecycle Automation
88+
89+
**Hooks** execute custom shell commands at specific points during an agent session. Use them to add validation, custom linting, security scanning, or notification workflows.
90+
91+
Available hook points:
92+
- `pre-run` — before Copilot begins working
93+
- `post-run` — after Copilot finishes working
94+
95+
Create `.github/copilot/hooks.yaml`:
96+
97+
```yaml
98+
hooks:
99+
post-run:
100+
- name: Run custom linter
101+
run: npm run lint -- --max-warnings 0
102+
- name: Check for TODO comments
103+
run: |
104+
if grep -r "TODO" src/; then
105+
echo "Warning: TODO comments found in src/"
106+
fi
107+
```
108+
109+
If a hook exits with a non-zero status, Copilot will see the output and attempt to address the issue before completing its session.
110+
111+
---
112+
113+
## 🗒️ Part 4: Copilot Memory (Public Preview)
114+
115+
**Copilot Memory** allows the coding agent to persist facts it learns about your repository across sessions — so it builds up knowledge over time without you having to repeat context.
116+
117+
To enable Copilot Memory:
118+
1. Navigate to your [GitHub Copilot settings](https://github.com/settings/copilot).
119+
2. Enable **Copilot Memory** (available for Pro and Pro+ plans).
120+
3. After a session completes, Copilot will write memory entries such as: "This project uses better-sqlite3, not the default sqlite3 package."
121+
122+
---
123+
124+
In the above exercises we achieved the following:
125+
- ✅ Built specialized custom agent profiles
126+
- ✅ Configured MCP server access
127+
- ✅ Set up lifecycle hooks for post-run validation
128+
- ✅ Understood Copilot Memory for persistent context
129+
130+
---
131+
132+
[← Previous: Instructions and Review](2-Instructions-and-Review.md) | [Next: Security and SDLC →](4-Security-and-SDLC.md)

0 commit comments

Comments
 (0)