GitHub Copilot Code Review Custom Instructions for Production

The production verdict

Custom instructions are useful when a review requires architectural context, but they are the wrong place for policy that must always pass. A model can recognize that a new billing write bypasses your authorization boundary. A required status check can prove that the test suite and static analysis completed. Keep those jobs separate.

GitHub explicitly documents custom instructions as non-deterministic and lists an instruction that tries to block a pull request as unsupported. That makes Copilot an advisory reviewer, even when its comments are excellent. Our deeper comparison of Copilot security review and CodeQL shows the same dividing line: semantic review can widen coverage, while a deterministic check owns the merge decision.

The head branch is now part of the threat model

Treat every review instruction loaded from the pull request head branch as untrusted input. On July 17, 2026, GitHub changed Copilot code review to read copilot-instructions.md, path-specific instruction files, agent skills, and AGENTS.md from the head branch rather than the base branch. It also added REVIEW.md, GEMINI.md, and CLAUDE.md to the files Copilot can read. GitHub's release note is the current source of truth for that behavior.

The change is valuable because an instruction edit can be tested before it is merged. It also means a pull request can influence the guidance used to review that same pull request. A contributor could weaken a check, introduce conflicting guidance, or bury the relevant rule under noise. The correct response is not to reject head-branch customization. It is to make instruction changes visible, owned, and independently reviewed.

Use a base-branch CODEOWNERS file to protect every surface that can alter review behavior:

/.github/            @acme/platform-security
/AGENTS.md           @acme/platform-security
/REVIEW.md           @acme/platform-security
/CLAUDE.md           @acme/platform-security
/GEMINI.md           @acme/platform-security

GitHub reads CODEOWNERS from the base branch when it requests owners, so a contributor cannot remove the reviewer requirement merely by editing ownership in the head branch. Pair that file with a ruleset that requires code-owner approval. GitHub's own CODEOWNERS guidance recommends owning the CODEOWNERS file itself or the full .github directory.

For a public repository, apply the same model to fork pull requests. The instruction content is contributor-controlled, while ownership, required checks, secrets, and network policy remain maintainer-controlled. Never expose a credential merely because a review instruction asks for external context.

Put each rule in the narrowest instruction surface

Use the smallest scope that matches the rule. Repository-wide instructions should contain only invariants that make sense across the codebase. Language, service, or directory rules belong in path-specific files. Cross-agent conventions belong in AGENTS.md when you genuinely want every supported agent to inherit them.

A clean monorepo layout looks like this:

.github/
  copilot-instructions.md
  instructions/
    api.instructions.md
    billing.instructions.md
    migrations.instructions.md
AGENTS.md
REVIEW.md

Keep the repository-wide file short and semantic:

## Review priorities

- Flag write paths that bypass the repository's approved authorization guard.
- Flag a new dependency from a domain package into a delivery adapter.
- Do not comment on formatting handled by the repository formatter.
- When a rule applies, name the affected boundary and the changed path.

Then scope a service-specific rule with applyTo frontmatter:

---
applyTo: "services/billing/**/*.ts"
---

## Billing review checks

- Flag a state-changing handler that does not call `authorizeBillingWrite` before persistence.
- Flag a retry path that can submit the same charge without an idempotency key.
- Ignore generated clients under `services/billing/generated/`.

The GitHub code review documentation defines .github/copilot-instructions.md for repository-wide rules, .github/instructions/**/*.instructions.md for path-specific rules, and root AGENTS.md for standing cross-agent context. Avoid copying the same rule into every supported file. A single owned source is easier to test, trace, and retire.

Write review checks, not aspirations

A good instruction identifies a trigger, a violated invariant, and the evidence a reviewer should cite. GitHub recommends beginning with 10-20 specific instructions and warns that quality may deteriorate when a single file grows beyond about 1,000 lines. Those are ceilings, not targets. A focused file with a small set of high-value checks is easier to evaluate than a policy encyclopedia.

GitHub also documents several hard limits: Copilot may not follow every instruction consistently, it cannot be instructed to block a merge, and it will not follow an external standards link as a substitute for embedded guidance. The custom-instructions tutorial is clear on those constraints. Design the system so a missed instruction is measurable, not catastrophic.

Isolate the review environment

Give code review its own minimal setup workflow when its runtime needs tools or repository metadata. GitHub now supports .github/workflows/copilot-code-review.yml; when that file is absent, code review falls back to .github/workflows/copilot-setup-steps.yml. A dedicated file prevents cloud-agent setup from silently becoming code-review setup.

For a TypeScript service, the review environment can be explicit and read-only:

name: Copilot Code Review Setup

on:
  workflow_dispatch:

jobs:
  copilot-setup-steps:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v6

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: "20"
          cache: npm

      - name: Install locked dependencies
        run: npm ci

The job name must remain copilot-setup-steps, and contents: read is the permission needed when the setup checks out the repository. Keep dependency installation lockfile-based. Do not add deployment credentials, write tokens, or broad network access just to improve a review comment.

The default GitHub-hosted review environment now runs behind a firewall, and the firewall is enabled by default for all repositories. Self-hosted runners do not support that integrated firewall, so they need an independently enforced egress policy. The environment documentation also matters for failure handling: when a setup step exits non-zero, Copilot skips the remaining steps and starts with the current environment state. Log setup status and make missing review context visible, because a degraded review can otherwise look like a clean review.

Promote instructions through an eval gate

Ship instruction changes like code: test them against labeled pull requests, inspect failures, and require an owner to promote them. A review instruction is a classifier expressed in natural language. Its useful output is a relevant finding at the correct location. Its failure modes are missed defects, noisy comments, contradictory advice, and comments on excluded paths.

Create a small eval record for each representative change:

case_id: billing-authz-bypass
changed_paths:
  - services/billing/api/charge.ts
expected_findings:
  - rule: billing-write-authorization
    evidence: persistence occurs before authorizeBillingWrite
forbidden_findings:
  - formatting-only comment
  - generated-client comment

Then run the same cases before and after an instruction edit.

The merge boundary stays deterministic. GitHub rulesets can require code-owner reviews and status checks, and required checks must pass before merge. Use tests, linters, architecture checks, secret scanning, and CodeQL where their result must be enforceable. Use Copilot findings to start a human review or improve the deterministic suite. Do not convert an uncalibrated model comment into a hidden gate.

This separation also makes the rollout reversible. You can disable a noisy instruction without weakening branch protection, and you can tighten a required check without rewriting the model context. That is the operating pattern behind our broader production coding systems: context improves judgment, while explicit controls preserve accountability.

Log quality, spend, and silent coverage gaps

Log enough context to explain why a review helped, failed, or never ran. At minimum, join the review request to the repository, pull request, head commit, instruction commit, loaded instruction files, review effort, setup status, firewall mode, comments, comment dispositions, AI credits, and GitHub Actions minutes.

A practical event shape is:

{
  "repository": "payments-api",
  "pull_request": "ref:pr",
  "head_sha": "ref:commit",
  "instructions_sha": "ref:instructions",
  "instruction_files": [".github/copilot-instructions.md"],
  "review_effort": "Low",
  "setup_status": "passed",
  "firewall_mode": "github-hosted-default",
  "comment_dispositions": ["useful", "noise"],
  "ai_credits": "from-billing-export",
  "actions_minutes": "from-actions-metrics"
}

GitHub currently exposes Low and Medium review effort. Low is the default. Medium is in public preview and consumes more AI credits and GitHub Actions minutes, so route it to security-sensitive or cross-service changes only after its added findings justify the spend.

Each review has two cost components: model usage billed in AI credits and agentic infrastructure billed in Actions minutes. One AI credit equals $0.01 USD, but the model chosen for code review is automatic and not disclosed, so cost per review can vary. In Actions metrics, filter for copilot-pull-request-reviewer. In the billing usage report, filter workflow_path by dynamic/agents/copilot-pull-request-reviewer. GitHub's billing reference documents both filters.

These silent gaps deserve alerts:

• A budget can block code review. The human and deterministic review path must continue when the applicable budget is exhausted.
• Automatic review runs only once unless review of new pushes is enabled. Log the reviewed head commit and detect a newer unreviewed commit.
• Dependency management files such as package.json and Gemfile.lock, log files, and SVG files are excluded from Copilot code review. Keep dependency, secret, and artifact checks outside the model reviewer.

The dashboard that matters is not comment volume. It is useful findings by rule, false-positive burden, missed labeled issues, degraded reviews, unreviewed head commits, and cost per useful finding. Those measures tell you whether the instruction layer is improving engineering throughput or merely moving review work around.

The durable decision rule

Use Copilot instructions for rules that need repository context and semantic judgment. Use path scope to keep those rules precise, a labeled eval set to prove they help, and owner review to control changes. Keep merge authority in rulesets, required checks, code scanning, and accountable humans.

The July 17 head-branch change makes instruction testing faster, but it also makes governance non-optional. A production rollout succeeds when every review can be traced to the exact instruction and code revision, every degraded run is visible, every material comment can be evaluated, and the repository remains safe when Copilot misses a check or does not run.