DEV Community

Tito O
Tito O

Posted on

GitHub Copilot Should Use .copilot, Not .github

GitHub Copilot is a cross-platform tool. It is available in VS Code, JetBrains, and Neovim, and it functions regardless of whether your code is hosted on GitHub, GitLab, or a self-hosted Bitbucket instance. It is a developer tool, not a hosting-specific feature.

Yet, the current configuration requirements are tied strictly to a specific hosting provider's directory. At present, the tool expects custom instructions to live within .github:

  • Custom Instructions: .github/copilot-instructions.md
  • Agent Configurations: .github/instructions/

By tethering a cross-platform assistant to a platform-specific directory, we create unnecessary confusion for teams and contributors.

1. Breaking Established Conventions

The .github folder has a well-defined purpose: managing features that live on GitHub’s servers. This includes GitHub Actions (/workflows), CODEOWNERS, and ISSUE_TEMPLATE. These files are inherently linked to the host; if you migrate to a different platform, they become dead weight.

Copilot is different. It runs locally in the IDE. It doesn't require a specific remote host to help you refactor code or document an API. Forcing its configuration into a platform-branded folder breaks the logic of how repository metadata is organized.

2. Cross-Platform Confusion

For teams using GitLab, Bitbucket, or Azure DevOps, adding a .github folder is a "vendor leak." It creates several practical issues:

  • Organizational Policy: Many companies have rules against platform-branded clutter in repositories hosted on competing services.
  • Contributor Friction: A developer seeing a .github folder in a non-GitHub repo will naturally wonder if the project is mirrored, if a migration is in progress, or if they are in the wrong place. This is "documentation debt" that shouldn't exist.

3. The "Junk Drawer" Effect

The .github directory is already crowded. It manages CI/CD, security policies, and sponsorship configs. Adding AI instructions, agent behaviors, and prompt templates turns it into the repository's junk drawer.

A dedicated .copilot directory allows the .github folder to stay focused on platform governance while giving AI tools a clean, dedicated space to evolve.

4. Portability and the Multi-AI Future

Many developers now use a stack of AI tools—Copilot for completions, Claude for deep refactors, or specialized tools like Cursor. A tool-specific structure is more professional and scalable:

my-project/
├── .copilot/       # Copilot-specific instructions & agents
├── .cursor/        # Cursor rules
├── .claude/        # Claude context files
└── .github/        # Actual GitHub platform features (Actions, etc.)
Enter fullscreen mode Exit fullscreen mode

This structure is modular. If a team switches tools, they can remove one directory without accidentally breaking their CI/CD or code ownership settings.

5. The Precedent of Neutrality

The most successful developer tools avoid branding their configuration folders after the platform that built them:

  • VS Code uses .vscode/, not .github/vscode/.
  • Prettier uses .prettierrc.
  • EditorConfig uses .editorconfig.

These tools work everywhere, and their configuration reflects that. Using .github for a tool that lives in the IDE is like parking your car in a neighbor’s driveway just because they are your landlord—it works, but it’s the wrong place for it.

The Solution: A Phased Migration

Moving to a new standard doesn't have to be a breaking change. A simple "search order" would solve the problem:

  1. Primary: The tool looks for .copilot/instructions.md.
  2. Fallback: The tool looks for .github/copilot-instructions.md for legacy support.
  3. Migration: Provide a command-line prompt to help users move their files to the new location.

A Call to Action

Platform-agnostic tools deserve platform-agnostic configurations. By adopting .copilot, we support a cleaner, more flexible future for AI-assisted development.

What do you think? Does it feel "off" to have a .github folder in your non-GitHub repos? Let’s discuss the best way to organize the next generation of developer tools.

Top comments (0)