Skip to main content

Buyer guide

GitHub Copilot Workflow Playbook

Repository instructions, agent-ready issues, and a review routine for cloud agent pull requests.

Reading time
4 min read
Sources
13 cited
In this piece
GitHub Copilot+15 Mixed

The call

Write build and test commands into .github/copilot-instructions.md, pre-install dependencies with copilot-setup-steps.yml, and assign the agent only issues with complete acceptance criteria.

Protect the instruction files with CODEOWNERS, and require a person other than the requester to approve every agent pull request.

Copilot's cloud agent opens pull requests that merge when it can build and test its own changes, and when each issue fits one branch and one session. Besides its own instruction file, Copilot follows AGENTS.md, CLAUDE.md and GEMINI.md, so one written setup can serve every coding agent a team runs. Hold its pull requests to a colleague's standard whether the work started in the cloud, the IDE, or the terminal.

When you need this

  • Your organization has enabled the Copilot cloud agent, or is about to, and teams are unsure which work to assign it.
  • Reviewers close or rewrite agent pull requests, and nobody has written down what the agent should know about the repository.
  • Engineers move between agent mode in the IDE, Copilot CLI, and the cloud agent with no shared practice.
  • Copilot code review comments repeat what CI already checks, and reviewers have started ignoring them.

Evaluation criteria

  1. Write the repository instructions

    What does a new engineer need to know to build and test a change here, and is it written where Copilot reads it?

    Look forPut build and test commands in .github/copilot-instructions.md. Describe the project layout and conventions there. Use NAME.instructions.md files for path-specific rules. Copilot also reads the nearest AGENTS.md or a single root CLAUDE.md or GEMINI.md, so agents can share instructions. The first cloud-agent pull request links to a generated starting file.

  2. Prepare the agent's environment

    Can the cloud agent install dependencies and run your tests on its runner without guessing?

    Look forPre-install tools and dependencies with copilot-setup-steps.yml. Keep the default GitHub and Playwright MCP servers on. Add other MCP servers one at a time, each for a stated need. GitHub's guidance is that an agent that builds and tests its own changes produces pull requests that merge faster.

  3. Write issues the agent can finish

    Would this issue work as a prompt for an engineer who has never seen the codebase, and does it fit one branch and one session?

    Look forWrite a clear problem statement and complete acceptance criteria. Name the files to change. GitHub recommends test coverage, bug and flaky-test fixes, configuration, and documentation as first tasks. Keep broad refactors, production-critical work, security-sensitive work, ambiguous tasks, and learning tasks with people. Split larger work, because a session stops at 59 minutes and opens one pull request per task.

  4. Pick where the task runs

    Does this work need an engineer steering in real time, or can it run in the background and come back as a pull request?

    Look forUse IDE agent mode or Copilot CLI when an engineer directs the work live. Delegate unattended issues to the cloud agent. Track sessions across repositories in the Copilot app. Plans, instructions, agent skills, and MCP servers transfer between tools where supported.

  5. Steer through the pull request

    How will engineers correct the agent once it has started?

    Look forMention @copilot in review comments. Batch comments with Start a review so the agent receives them together. Read session logs alongside the diff. Copilot responds only to people with repository write access.

  6. Review it like a colleague's pull request

    Who approves agent work, and what must pass before it merges?

    Look forRequire a person with write access to approve Actions workflows on agent commits. Prevent requesters from approving their own agent pull requests. Require code scanning or other checks through rulesets, and have a reviewer read the diff. The agent cannot mark its own pull request ready, approve it, or merge it.

  7. Protect the instruction files

    Can a pull request change the instructions Copilot uses on that same pull request?

    Look forProtect .github/copilot-instructions.md, .github/instructions, AGENTS.md, and MCP configuration with CODEOWNERS and Require review from Code Owners. Copilot code review reads instructions and agent skills from the pull request's head branch.

Questions to ask vendors

  1. Which of our rulesets or branch protection rules will block the cloud agent, for example rules that restrict commit authors, and how do we test that before rollout?
  2. Who streams our audit log to the SIEM before events age out? GitHub keeps them for 180 days, and the actor:Copilot search shows agent activity.
  3. How many AI credits and GitHub Actions minutes did our pilot repository's agent sessions use, by user and by model?
  4. Which third-party coding agents can run in our repositories under the same protections, and how is their usage billed?

Red flags

  • The cloud agent enabled in a repository with no copilot-instructions.md or AGENTS.md.
  • Issues assigned to the agent that need more than one branch, one pull request, or 59 minutes of work.
  • Workflows set to run automatically on agent pull requests before anyone has approved them.
  • Instruction files and MCP configuration that anyone can change without code owner review.
  • Agent pull requests merged on the strength of the session log, without a person reading the diff.

Products in this piece

Sources

Official documentation
10
Public source
3
  1. GitHub Copilot docs: Repository custom instructionsOfficial documentationdocs.github.com
  2. GitHub Copilot docs: Best practices for using Copilot to work on tasksOfficial documentationdocs.github.com
  3. GitHub Copilot docs: Piloting the cloud agent in your organizationOfficial documentationdocs.github.com
  4. GitHub Copilot docs: Copilot on GitHub.com and the cloud agentOfficial documentationdocs.github.com
  5. GitHub Copilot docs: Cloud agent risks and mitigationsOfficial documentationdocs.github.com
  6. GitHub Copilot docs: Building guardrails for the cloud agentOfficial documentationdocs.github.com
  7. GitHub Copilot docs: Configure MCP servers for your repositoryOfficial documentationdocs.github.com
  8. GitHub Copilot docs: Where to use GitHub CopilotOfficial documentationdocs.github.com
  9. GitHub Copilot docs: Third-party coding agentsOfficial documentationdocs.github.com
  10. GitHub Copilot docs: Reviewing audit logsOfficial documentationdocs.github.com
  11. Hacker News: brushfoot on handing a Markdown spec to the Copilot agent (Oct 15, 2025)Public sourcenews.ycombinator.com
  12. Hacker News: webworker on writing issues for Copilot agents (Apr 28, 2026)Public sourcenews.ycombinator.com
  13. Angie Jones: How I taught GitHub Copilot code review to think like a maintainer (Nov 10, 2025)Public sourceangiejones.tech

Keep reading

  1. Buyer guideMoving Off Continue: A Migration ChecklistInventory a team's Continue setup and carry its models, rules, MCP servers, and prompts to a maintained tool, and run a pilot before removing Continue.
  2. Buyer guideGitHub Copilot AI Credit Budget & Policy ChecklistThe budget controls to set under AI credits, in GitHub's order, sized with GitHub's method, plus model and code review billing policy.
  3. Buyer guideRolling Out Copilot Code ReviewWhich repositories get Copilot review first, how to tune its comments, which effort level to use, and who is billed for each review.
Read the research