Custom Instructions

Custom instructions let you fine-tune how GitHub Copilot performs code reviews by giving it project-specific context and priorities.

1 ✏️ Enabling
2 ✏️ Disabling
3 Tips
- 3.1 General Guidelines
- 3.2 Common Topics to Include
- 3.3 Example

Using custom instructions helps ensure Copilot’s feedback better aligns with your team’s specific conventions and priorities rather than generic suggestions. GitHub Docs

For example, you might add a .github/copilot-instructions.md file that says:

“When reviewing code: focus first on security issues (e.g., input validation, secrets), then on performance (e.g., N+1 queries), then on readability and proper naming.”

You can also specify path-scoped instruction files (e.g., files under .github/instructions/ with *.instructions.md) that apply only to certain directories or modules—for example:

Front-end files should emphasize accessibility and consistent UI patterns.

The more context you can add to these files, the more Copilot’s output will be in line with your expectations. Note that instructions files used by Copilot for both reviewing code as well as writing it.

✏️ Enabling

In your repository, create the instruction file(s):
- For repository-wide: .github/copilot-instructions.md
- For path-specific: .github/instructions/<name>.instructions.md with an applyTo: section specifying directory globs. GitHub Docs
Add your natural-language guidance inside the file, e.g.:
# Code Reviewer Instructions - Always check for API misuse and secret exposure - Use descriptive names, avoid nested loops >3 levels - Comments should exist for any public method ``` :contentReference[oaicite:5]{index=5}
Save and commit the file. Copilot will automatically use these custom instructions when performing code reviews in that repo (or for files matching path scopes).

✏️ Disabling

Go to your repository’s Settings → Copilot → Code review
Locate the toggle/menu for “Repository custom instructions” or a similar setting. By default, this feature is enabled.

Set the toggle to Disabled (or remove the custom instructions file from the repository) to stop Copilot from using those instructions.
Optional: If you disable at org level, ensure that repository-level settings are aligned (so that custom instructions are not inherited). The GitHub Blog

Tips

Custom instructions work best when they’re clear, concise, and aligned with your team’s priorities. Copilot reads this file as natural language — not code — so think of it like writing directions to a new teammate.

General Guidelines

Be specific, not vague.
✅ “Flag any database query without pagination.”
🚫 “Check for performance problems.”
Focus on priorities. Tell Copilot what matters most (e.g., security > performance > style).
Keep it short. 5–10 focused bullet points are ideal — long lists dilute clarity.
Use plain English. Copilot understands natural instructions better than dense technical prose.
Review it regularly. Update the file as your project evolves or new patterns emerge.

Common Topics to Include

Focus Area	Example Instructions

Focus Area	Example Instructions
Security	“Warn about hardcoded secrets or missing input validation.”
Performance	“Flag nested loops, inefficient database queries, or unbatched network calls.”
Readability	“Encourage descriptive variable names and clear function signatures.”
Testing	“Remind reviewers if new features lack unit or integration tests.”
Accessibility	“Highlight missing ARIA labels or low-contrast color combinations in UI code.”
Error Handling	“Ensure all API calls handle failure conditions gracefully.”
Architecture / Design	“Call out circular imports or violations of established module boundaries.”
Documentation	“Suggest adding docstrings for exported functions or public classes.”

Example

# Code Reviewer Instructions

When reviewing code:
- Focus first on **security** (e.g., input validation, secret exposure).  
- Then check for **performance issues** (e.g., N+1 queries, large loops).  
- Verify **test coverage** for new or changed logic.  
- Maintain **consistent naming** and ensure comments explain *why*, not *what*.  
- For frontend code, **check accessibility** (ARIA, keyboard focus, contrast).