Sharing GitHub Copilot Instructions Across Repos and Teams

Your AI assistant starts every conversation as a blank slate. It doesn’t know your team uses COALESCE instead of ISNULL. It doesn’t know your naming conventions, your commit message format, or the three anti-patterns that have caused production incidents twice this year. Every developer on your team is teaching their AI assistant from scratch, one correction at a time.

GitHub Copilot supports custom instruction files that solve this problem, but only if every repository has one. The question nobody seems to be answering is: how do you keep those files consistent across 5, 50, or 500 repositories?

This post covers what instruction files are, why sharing them matters, and five practical methods for distributing them across repos and teams, including options for Bitbucket, Azure DevOps, and GitLab.

The Instruction Hierarchy

Before we talk about sharing, you need to understand what you’re sharing. GitHub Copilot reads instructions from multiple layers, and all relevant instructions are provided to the model. When instructions conflict, higher-priority layers win.

The priority order (highest to lowest):

1. Personal instructions – set via your GitHub.com profile (Copilot settings). These are stored server-side, not as a file.
2. Path-specific instructions – files matching .github/instructions/**/*.instructions.md, with YAML frontmatter¹ specifying which files they apply to.
3. Repository-wide instructions – the classic .github/copilot-instructions.md file. Plain Markdown, no frontmatter needed.
4. Agent instructions – AGENTS.md, CLAUDE.md, or GEMINI.md files anywhere in the repo. The nearest file in the directory tree wins.
5. Organization instructions – set in GitHub org settings (Copilot > Custom instructions). Requires Business or Enterprise tier.

VS Code also supports user-level instruction files in ~/.copilot/instructions/*.instructions.md (a folder of files, not a single file).

The GitHub Copilot CLI reads instructions from all these locations plus one more: $HOME/.copilot/copilot-instructions.md. This is a single global file that applies to every CLI session regardless of which repo you’re working in. If you use the CLI for agentic workflows (autonomous code generation, database maintenance scripts, multi-step refactoring), this file is your guardrail. It’s where you put rules like “never execute SQL against production without my approval” or “always validate PowerShell scripts before committing.”

You can verify which instruction files are active in a CLI session with the /instructions command, and the COPILOT_CUSTOM_INSTRUCTIONS_DIRS environment variable lets you add additional directories beyond the defaults.

One thing worth noting: Copilot code review only reads the first 4,000 characters of your repository-wide instructions file. If yours is longer than that, front-load the most important rules.

Why Sharing Matters

If you maintain more than one repository, you’ve probably already noticed the problem. Your main API repo has a polished instructions file. The three microservices that went live last quarter? They have no instructions at all. The frontend repo has instructions written by someone who left the team six months ago.

The consequences are predictable:

Inconsistency. Five repos, five different AI-generated SQL styles. One uses ISNULL, another uses COALESCE. One puts commas at the end of lines, another uses leading commas. Every code review becomes a style correction session.

Wasted onboarding time. A new developer joins the team and their Copilot generates code that violates conventions nobody wrote down. They learn the rules one PR comment at a time, and so does their AI assistant.

Repeated code review friction. The senior developer who enforces “always use explicit ANSI JOIN syntax” is now enforcing it against both humans and AI-generated code. The rules exist in their head, not in a file the AI can read.

Shared instructions fix this by encoding team knowledge once and distributing it everywhere. It’s mentorship that scales without meetings.

Method 1: Organization-Level Instructions

If your GitHub organization has a Copilot Business or Enterprise subscription, this is the simplest option. No files to sync, no CI/CD to configure.

Navigate to your org’s settings: Settings > Copilot > Custom instructions. Enter your organization-wide standards in the text box and save.

These instructions apply to all organization members when they use Copilot Chat, code review, or the cloud agent on GitHub.com.

Trade-offs:
– Zero maintenance overhead. Set it and forget it.
– Only works on GitHub.com, not in IDEs (VS Code, JetBrains, etc.) as of mid-2026.
– Lowest priority in the hierarchy, so repo-level instructions override them.
– Requires Business or Enterprise tier.

Best for: High-level organizational standards (preferred languages, security policies, documentation requirements) that complement repo-specific instructions.

Method 2: Template Repositories

GitHub template repositories let you create a starting point for new repos. If your template includes .github/copilot-instructions.md, every repository created from it inherits that file.

To set up a template:

1. Create a repository with your standard instructions file, README, PR template, and other boilerplate.
2. In the repository’s settings on GitHub.com, go to Settings > General and check Template repository.
3. New repos can now be created via Use this template > Create a new repository, or with gh repo create --template your-org/template-repo.

The critical caveat: Template repositories are a one-time copy. There is no ongoing link between the template and the downstream repos. If you update the instructions in the template next month, every repo you created from it last month still has the old version.

Trade-offs:
– Trivial to set up.
– Great for bootstrapping new repos with a consistent baseline.
– No ongoing synchronization. Updates don’t propagate.
– Combine with another method (like Actions sync) for ongoing maintenance.

Best for: Teams that create new repos regularly and want a consistent starting point, but plan to layer on a sync mechanism for updates.

Method 3: GitHub Actions File Sync

This is the workhorse solution. A central “standards” repository holds the canonical version of your instructions file. When you push changes to that file, a GitHub Action automatically opens pull requests (or pushes directly) to every target repository.

The most popular option is BetaHuhn/repo-file-sync-action (around 1,100 stars on GitHub). Here’s a working setup:

In your central standards repo, create .github/sync.yml:

Then create the workflow at .github/workflows/sync.yml:

When you update the instructions file and push to main, the action opens a PR in each target repo with the updated file. Reviewers in those repos can approve, modify, or reject the change.

Authentication matters. The default GITHUB_TOKEN can’t write to other repos. You need either a Personal Access Token (PAT) with repo scope, or (better) a GitHub App installation token. The App approach is preferable because it provides fine-grained per-repo permissions, an audit trail, and no dependency on a personal account.

Another solid option is wadackel/files-sync-action, which supports EJS templating² (useful if you need slight variations per repo) and fine-grained PAT support.

Trade-offs:
– Single source of truth with auditable, PR-based updates.
– Changes are visible and reviewable before they land.
– Requires a PAT or GitHub App token with cross-repo access.
– Some initial setup to list all target repos.

Best for: Teams that want ongoing synchronization with change visibility and review.

Method 4: CI/CD Sync on Other Platforms

Not everyone is on GitHub. The good news is that the core pattern is the same everywhere: clone the target repo, copy the file, commit, push. The wrapper differs by platform.

Bitbucket Pipelines

Bitbucket has no equivalent to copilot-instructions.md (Atlassian Intelligence doesn’t read repo-level instruction files). But if your developers use VS Code with GitHub Copilot against a Bitbucket-hosted repo, the IDE still reads .github/copilot-instructions.md from the local checkout.

To sync across Bitbucket repos, create a custom pipeline in your central config repo:

Trigger this via a bitbucket-pipelines.yml custom pipeline, and optionally schedule it via the Bitbucket UI (Pipelines > Schedules).

Azure DevOps

Azure DevOps doesn’t have its own AI instruction mechanism, but copilot-instructions.md works locally in developer IDEs regardless of where the repo is hosted. Cross-repo sync uses the same script pattern, triggered by an Azure Pipeline:

Azure Pipelines also supports resources.repositories for pulling files from other repos at pipeline time, which can be useful for pipeline templates but doesn’t directly copy files into the target repo’s working tree.

GitLab CI/CD

GitLab Duo doesn’t read a per-repo instruction file (its settings are UI-based). As with Bitbucket, the file still works locally in VS Code.

GitLab’s CI/CD has the most powerful native cross-project triggering:

GitLab also supports multi-project pipelines (trigger: project:) to kick off downstream pipelines, which can be useful if target repos need to run their own validation after receiving the updated file.

The Universal Pattern

Regardless of platform, the sync script is fundamentally the same: clone, copy, diff, commit, push. The sync-instructions.sh script shown in the Bitbucket section works in any CI environment that has Git installed. Adapt the clone URL and authentication to your platform.

Method 5: Personal/Global Instructions

The methods above handle per-repo instructions. But what about your personal instructions that follow you across all repos and machines?

There are two personal instruction mechanisms depending on your tooling:

• VS Code reads user-level instruction files from ~/.copilot/instructions/*.instructions.md (a folder of .instructions.md files).
• GitHub Copilot CLI reads a single global file at $HOME/.copilot/copilot-instructions.md.

The CLI file is especially important for agentic DBA workflows. When you’re using the CLI to autonomously generate migration scripts, audit database configurations, or write deployment procedures, your global instructions are the persistent set of rules the agent follows. Without them, every new CLI session starts with zero context about your team’s conventions.

To sync these across machines, you have three options ranked by complexity:

Option 1: Dotfiles repo + symlink (simplest)

One git pull updates every machine.

Option 2: yadm (minimal tooling)

yadm is a thin wrapper around a bare git repo rooted at $HOME. It manages dotfiles without symlinks:

On a new machine: yadm clone git@github.com:you/dotfiles.git.

Option 3: chezmoi (full-featured)

chezmoi is the heavy-duty option. It supports Go templates (different instructions on work vs. personal machines), encrypted secrets, and integration with password managers. It’s best suited for developers who already manage complex dotfile setups across multiple machines.

Choosing the Right Method

There’s no single right answer. Your choice depends on your organization’s platform, subscription tier, and how many repos you need to cover.

Most teams will use a combination. Organization-level instructions for broad standards, a central repo with Actions sync for team-specific rules, and individual dotfiles for personal preferences.

What to Put in Your Instructions

A shared instructions file is only useful if it contains the right things. I wrote a deeper dive on this in Teaching AI Your Environment: Custom Instructions and Context, but here’s a rough value hierarchy:

High value (put these in first):
– Code formatting standards (indentation, brace style, comma placement)
– Anti-patterns to avoid (“never use SELECT * in production code”)
– Product nomenclature (“ProjectX and Phoenix are the same product; never confuse them”)
– Error handling patterns (try/catch structure, logging requirements)
– SQL conventions (join style, parameter handling, naming)

Medium value:
– Preferred libraries and frameworks
– Testing conventions (file naming, assertion style)
– Commit message format
– Documentation requirements

Low value (probably skip):
– Obvious language features the model already knows
– Editor-specific preferences (that’s what .editorconfig³ is for)
– Aspirational rules nobody actually follows⁴

Keep your repository-wide file under 4,000 characters if you use Copilot code review, since it only reads that far. If you need more, move specialized rules to path-specific instruction files.

A real-world example

Here’s a sanitized excerpt from a production instructions file. This is a global file that applies across all repos for a DBA who works primarily with T-SQL and PowerShell:

Notice the specificity. “Use COALESCE instead of ISNULL” is actionable. “Write good SQL” is not.

Treat Instructions as Code

Your instructions file is a living document. It will grow as your team discovers new patterns and anti-patterns. Treat it the way you treat any other shared configuration:

• Version it. It’s already in git. Use meaningful commit messages when you update it.
• Review changes. If you’re using Actions sync, changes arrive as PRs. Review them.
• Prune regularly. Instructions that no longer apply create confusion. Remove them.
• Test the output. After changing instructions, generate some code and verify the AI actually follows the new rules.

A word about security: Shared instruction files are visible to anyone with repository access, and their contents are sent to the AI service as conversation context. Never put credentials, connection strings, or real server names in a shared instructions file. Use generic placeholders in shared files and keep environment-specific details in local files that aren’t committed to version control. I covered this in detail in Teaching AI Your Environment – see the “Security: What NOT to Put in Shared Instructions” section.

Further Reading

• Adding repository custom instructions for GitHub Copilot (GitHub Docs)
• Adding organization custom instructions (GitHub Docs)
• Custom instructions in VS Code (VS Code Docs)
• BetaHuhn/repo-file-sync-action (GitHub)

If you’re interested in other ways to give your AI assistant long-term memory, check out Teaching Your AI Assistant to Remember: Session Checkpoints for Multi-Day Work.

What does your instructions file look like? I’m curious what rules other teams are encoding. Let me know on Bluesky or LinkedIn.

---

¹ YAML frontmatter is a block of metadata at the very top of a Markdown file, delimited by triple dashes (---). It’s parsed separately from the Markdown content and used to attach structured data (like configuration or routing rules) to the file. For path-specific instruction files, the frontmatter tells Copilot which source files the instructions apply to:

² EJS (Embedded JavaScript) templating lets you insert dynamic values into a file using <%= variable %> placeholders. In the context of file sync, this means you can maintain one instructions template and substitute repo-specific values (like a project name or database engine) at sync time, so each target repo gets a slightly customized version of the shared file.

³ .editorconfig is a cross-editor configuration file that standardizes basic formatting settings (tabs vs. spaces, indent width, line endings, charset) per project. You place it in the repo root and most editors (VS Code, Visual Studio, JetBrains, Notepad++) apply the settings automatically. It handles the formatting layer so your Copilot instructions can focus on code logic and conventions.

⁴ Examples: “All functions must have unit tests” (current coverage: 12%). “Every table must have a clustered index” (see: heap_audit_results_2019_FINAL_v3.xlsx). “No TODOs in committed code” (grep says 347). “All stored procedures must have error handling” (laughs in BEGIN TRY).