Chapter 13: Copilot Coding Agent — Setup & Operations
Part V: Agentic Development Prerequisites: Chapter 5: Copilot Policies & Content Controls, Chapter 12: GitHub Actions & CI/CD Workflows GH-100 Exam Mapping: Beyond GH-100 — Enterprise Copilot mastery Verified: 2026-02-01 against official documentation
1. Introduction
Learning Objectives
After completing this chapter, you will be able to:
- Explain the Copilot coding agent architecture, including its GitHub Actions-based sandbox environment and security boundaries
- Enable the coding agent policy at enterprise, organization, and repository levels with appropriate access controls
- Assign issues to Copilot and manage the end-to-end agent workflow from issue to merged pull request
- Review agent-created pull requests, iterate on feedback, and configure compute budgets and usage limits
- Customize the agent development environment using
copilot-setup-steps.ymland custom instruction files
Exam Domain Coverage
| Domain | Topics in This Chapter |
|---|---|
| Beyond GH-100 | Coding agent architecture, policy enablement, issue assignment, agent workflow lifecycle, PR review, sandbox security, billing and premium requests, custom instructions |
Chapter Overview
This chapter marks the beginning of Part V: Agentic Development, which represents a fundamental shift in how enterprise teams interact with GitHub Copilot. Until now, every chapter in this book has covered tools where a human developer initiates each action -- writing code in an IDE (Integrated Development Environment), running CLI (Command-Line Interface) commands, or configuring policies through a web interface. The Copilot coding agent changes this dynamic entirely. It is GitHub's first asynchronous software engineering agent: an autonomous AI developer that reads an issue, creates a branch, writes code, runs tests, opens a pull request (PR), and iterates on feedback -- all without a human touching a keyboard.
For enterprise organizations with 200 or more developers, the coding agent is not a novelty. It is a force multiplier. Teams that process hundreds of issues per sprint can delegate well-scoped tasks -- bug fixes, test additions, documentation updates, dependency upgrades, and even small features -- to Copilot. The agent works in the background, producing draft PRs that human reviewers can approve, request changes on, or reject. Every action the agent takes is visible in the PR timeline, every line of code is reviewable, and every CI (Continuous Integration) check must pass before the code can merge. The governance controls you established in Chapter 5: Copilot Policies & Content Controls and the GitHub Actions pipelines you built in Chapter 12: GitHub Actions & CI/CD Workflows are the foundation that makes safe, autonomous agent work possible.
This chapter covers the coding agent from architecture through operations. You will learn how the agent's sandboxed environment works, how to enable it at every level of the enterprise hierarchy, how to assign issues and manage the agent workflow, how to review and iterate on agent-produced code, and how to control costs through premium request budgets. By the end of this chapter, you will have assigned your first issue to Copilot and reviewed the resulting pull request. Chapter 14: Agent Skills & Custom Agents builds on this foundation by showing how to extend the agent with custom skills and Model Context Protocol (MCP) servers.
2. Theory & Deep Dive
2.1 What Is the Copilot Coding Agent?
The Copilot coding agent is GitHub's hosted, autonomous AI developer. Unlike Copilot Chat -- which responds to prompts in real time within an IDE or the GitHub web interface -- the coding agent works asynchronously in the background. You assign it a task, and it operates independently in its own ephemeral development environment to produce a pull request.
The key distinction is the mode of interaction:
| Capability | Copilot Chat | Copilot Coding Agent |
|---|---|---|
| Interaction model | Synchronous, real-time | Asynchronous, background |
| Initiator | Developer types a prompt | Developer assigns an issue or delegates from chat |
| Output | Code suggestions, explanations, chat messages | Complete pull requests with commits, descriptions, and CI runs |
| Environment | Runs in the developer's IDE or browser | Runs in its own sandboxed GitHub Actions environment |
| Iteration | Immediate back-and-forth | PR review comments trigger new agent sessions |
| Code execution | Cannot run code (except in certain IDE agent modes) | Can build, test, lint, and validate code |
The coding agent is not a replacement for Copilot Chat. It is a complement. Chat handles interactive, exploratory work where you need immediate answers. The coding agent handles defined tasks where you can write a clear issue description and walk away while it works.
Enterprise Scenario: A platform engineering team at a 300-developer fintech company triages their backlog every Monday. Issues labeled
good-for-copilot-- typically well-scoped bug fixes, test coverage gaps, and documentation updates -- are bulk-assigned to Copilot. By Tuesday morning, the team has 15-20 draft PRs to review. Senior engineers spend their time reviewing agent output rather than writing boilerplate, reclaiming an estimated 40 hours of engineering time per week.
2.2 Architecture: The GitHub Actions Sandbox
The coding agent does not run on your machine, in your CI runners, or in any infrastructure you manage. It runs entirely within GitHub's hosted environment, built on top of GitHub Actions.
When you assign an issue to Copilot, the following sequence occurs:
- Task intake: The agent reads the issue title, body, labels, linked issues, and any referenced files. It also reads the repository's custom instructions (see Section 2.9).
- Environment provisioning: GitHub spins up an ephemeral Ubuntu x64 Linux runner -- the same infrastructure that powers GitHub Actions hosted runners. This runner is the agent's sandbox.
- Setup steps: If a
copilot-setup-steps.ymlfile exists in the repository (see Section 2.8), the agent runs it to install dependencies, configure tools, and prepare the build environment. - Repository checkout: The agent clones the repository into the sandbox and creates a new branch prefixed with
copilot/(for example,copilot/fix-login-timeout). - Code generation: The agent analyzes the codebase, plans its approach, and writes code. It can explore files, search for patterns, read documentation, and generate new code or modify existing files.
- Validation: The agent runs any build commands, tests, and linters configured in the setup steps. If tests fail, it iterates on the code within the same session.
- Pull request creation: The agent commits its changes, pushes to the
copilot/branch, and opens a draft PR with a description explaining what it did and why. - Review request: The agent requests a review from the developer who assigned the issue.
The sandbox has specific security characteristics:
- Read-only repository access: The agent has read access to the repository contents but can only push to branches beginning with
copilot/. It cannot push tomain,master, or any other branch. - Firewall-controlled internet: The sandbox has internet access, but it is controlled by a firewall. The agent can download packages from public registries but cannot make arbitrary outbound connections to internal corporate networks.
- Ephemeral environment: The sandbox is destroyed after the agent completes its work. No state persists between sessions. Each new session (including iterations triggered by review comments) starts from a fresh environment.
- No secrets access by default: GitHub Actions workflows do not run automatically on agent-created PRs. A user with write permissions must explicitly approve workflow runs, preventing the agent from accessing repository secrets.
Enterprise Scenario: A healthcare technology company with strict HIPAA (Health Insurance Portability and Accountability Act) compliance requirements evaluates the coding agent. Their security team reviews the architecture and notes that the agent never accesses production credentials, runs in an isolated sandbox, cannot merge its own code, and produces an auditable PR trail. They approve the agent for use on non-PHI (Protected Health Information) repositories, starting with internal tooling and developer experience projects.
2.3 Enabling the Coding Agent at the Enterprise Level
The Copilot coding agent is disabled by default for GitHub Copilot Business and GitHub Copilot Enterprise subscribers. Enabling it requires explicit action at up to three levels of the GitHub hierarchy: enterprise, organization, and repository.
Enterprise-Level Policy
Enterprise owners control the coding agent through the Copilot policies page. Navigate to your enterprise settings:
- Go to
https://github.com/enterprises/YOUR-ENTERPRISE/settings/copilot/policies - Locate the Copilot coding agent policy
- Select one of three options:
- Enabled: All users with a Copilot license across all organizations in the enterprise can use the coding agent
- Disabled: No users in the enterprise can use the coding agent, regardless of organization settings
- No policy: Delegates the decision to individual organization owners
For most enterprises, No policy is the recommended starting point. This allows individual organizations to pilot the coding agent independently, which is a common pattern for enterprises with multiple business units that have different risk profiles and adoption timelines.
You must also configure the MCP servers on GitHub.com policy if you plan to use Model Context Protocol servers with the coding agent (covered in Chapter 14: Agent Skills & Custom Agents):
- On the same Copilot policies page, locate the MCP servers on GitHub.com policy
- Select Enabled or No policy to allow MCP server usage
Enterprise Scenario: A global manufacturing conglomerate with 1,200 developers across six organizations sets the enterprise policy to "No policy." Their cloud platform organization (200 developers) enables the coding agent immediately for internal tooling repositories. Their embedded systems organization (150 developers) keeps it disabled until they complete a security review. Their application development organization (400 developers) enables it on a per-repository basis, starting with their developer portal project. This tiered rollout lets each business unit move at its own pace while the enterprise security team monitors usage through the audit log.
Organization-Level Policy
Organization owners enable the coding agent for their members:
- Go to
https://github.com/organizations/YOUR-ORG/settings/copilot/policies - Set the Copilot coding agent policy to Enabled
- Set the MCP servers on GitHub.com policy to Enabled (if needed)
Important: If the enterprise has set an explicit Enabled or Disabled policy, the organization cannot override it. The organization-level setting only takes effect when the enterprise policy is set to No policy.
Repository-Level Control
By default, when the coding agent is enabled at the organization level, it is available in all repositories for users who have access. Organization owners can restrict this:
- Go to organization settings under Copilot > Policies
- Under repository access for the coding agent, choose to allow all repositories or select specific repositories
This is particularly useful for organizations that want to pilot the agent on a small number of repositories before a broader rollout.
2.4 The Agent Workflow: From Issue to Merged PR
The complete lifecycle of a coding agent task follows a predictable pattern that integrates with the standard GitHub pull request workflow.
Step 1: Assign an Issue to Copilot
You can trigger the coding agent in several ways:
- Direct assignment: On any GitHub issue, assign it to @copilot (Copilot appears as an assignable user when the coding agent is enabled)
- From Copilot Chat on GitHub.com: Open the Copilot Chat panel on github.com, select a repository and branch, and describe the task. Copilot creates an issue and begins working.
- From VS Code: Use Copilot Chat in VS Code to delegate a task. Select "Send to Coding Agent" to have it work asynchronously on GitHub.
For enterprise teams, direct issue assignment is the most common pattern because it integrates with existing issue triage workflows and project boards.
When writing issues for the coding agent, clarity matters. The agent reads the issue title, body, any linked issues or discussions, and the repository's custom instructions. Well-scoped issues with clear acceptance criteria produce better results.
Example of a well-written issue for the coding agent:
## Title: Add request timeout configuration to HTTP client
## Description
The `HttpClientService` class in `src/services/http-client.ts` currently
uses a hardcoded 30-second timeout. We need to make this configurable
through environment variables.
## Requirements
- Read timeout value from `HTTP_CLIENT_TIMEOUT_MS` environment variable
- Default to 30000ms if the variable is not set
- Validate that the value is a positive integer
- Update the existing unit tests in `tests/services/http-client.test.ts`
- Add a new test for the environment variable configuration
## Acceptance Criteria
- [ ] Timeout is configurable via environment variable
- [ ] Default behavior is unchanged (30s)
- [ ] Invalid values fall back to default with a warning log
- [ ] All existing tests pass
- [ ] New tests cover the configuration path
Step 2: Agent Creates a Branch and Works
After assignment, the agent:
- Reads the issue and repository context
- Creates a branch named
copilot/followed by a descriptive slug (for example,copilot/add-timeout-config) - Works in its sandbox environment, making commits as it progresses
- Runs any configured build, test, and lint commands
The agent can only push to branches that start with copilot/. This is enforced at the Git level and cannot be overridden. Any branch protection rules that apply to copilot/* branches will be enforced.
Step 3: Agent Opens a Draft Pull Request
When the agent completes its work, it opens a draft PR that:
- Links back to the original issue
- Includes a description of what was changed and why
- Shows the full diff of all modifications
- Requests a review from the developer who assigned the issue
Critical security control: The PR is opened as a draft. GitHub Actions workflows will not run automatically on the agent's PR. A user with write permissions must click "Approve and run workflows" in the PR merge box before any CI pipeline executes. This prevents the agent from triggering workflows that have access to repository secrets.
Step 4: Human Reviews and Iterates
The review process works exactly like any other PR review:
- Review the code diff, PR description, and any agent-generated comments
- Leave review comments requesting changes, asking questions, or approving
- If you request changes, mention @copilot in your review comments to trigger the agent to start a new session and address your feedback
- The agent reads your comments, starts a new sandbox session (with full context from the previous session), and pushes new commits
Best practice: Batch your review comments into a single review submission rather than posting them one at a time. Each mention of @copilot in a PR comment triggers a new agent session, so batching is more efficient and produces better results.
Step 5: Approve Workflows and Merge
Once you are satisfied with the code:
- Click "Approve and run workflows" to allow CI checks to execute
- Wait for all checks to pass
- Approve the PR (note: the developer who assigned the issue to Copilot cannot approve the PR in repositories that require an approving review -- an independent reviewer is required)
- Merge the PR using your team's standard merge strategy (squash, merge commit, or rebase)
The agent cannot mark its own PRs as "Ready for review," cannot approve PRs, and cannot merge PRs. Every merge requires human approval.
2.5 The Model Behind the Agent
The Copilot coding agent uses a large language model (LLM) selected by GitHub for the task. As of early 2026, GitHub routes agent requests to the model that provides the best balance of code quality, reasoning depth, and cost efficiency. The specific model may change over time as GitHub evaluates new models.
Unlike Copilot Chat in the IDE (where users on Pro+ plans can select from multiple models including Claude Opus 4, OpenAI o3, and others), the coding agent's model selection is managed by GitHub. This ensures consistent behavior across all agent sessions and allows GitHub to optimize for the agentic workflow.
2.6 Costs and Billing
The coding agent consumes two types of resources:
Premium Requests
Each coding agent session consumes one premium request, regardless of the complexity of the task or the number of files modified. Premium requests are drawn from the monthly allowance associated with your Copilot license:
| Plan | Monthly Premium Request Allowance | Price |
|---|---|---|
| Copilot Free | 50 premium requests | $0 |
| Copilot Pro | 300 premium requests | $10/user/month |
| Copilot Pro+ | 1,500 premium requests | $39/user/month |
| Copilot Business | 300 premium requests per user | $19/user/month |
| Copilot Enterprise | 1,000 premium requests per user | $39/user/month |
Premium requests beyond the included allowance are billed at $0.04 USD per request.
GitHub Actions Minutes
The agent's sandbox runs on GitHub Actions infrastructure, consuming minutes from your account's GitHub Actions allowance. The minutes consumed depend on how long the agent takes to complete the task -- simple tasks may take 5-10 minutes, while complex tasks with extensive test suites may take 30 minutes or more.
GitHub Actions minutes are shared with all other workflows in your organization. Enterprise administrators should account for agent usage when planning their Actions minutes budget.
Budget Controls
Enterprise and organization administrators can set budgets for premium requests at multiple levels:
- Enterprise level: Set a maximum monthly spend across all organizations
- Organization level: Set per-organization limits
- Cost center level: Group organizations into cost centers for budget tracking
Budgets can be configured as a single bundled limit (combining all premium request types) or as individual SKU budgets with separate limits for Copilot Chat, Copilot coding agent, and other features. Since November 2025, premium requests for the coding agent are tracked in a dedicated SKU (Stock Keeping Unit), providing clear visibility into agent-specific costs.
Enterprise Scenario: A 500-developer enterprise on the Copilot Enterprise plan ($39/user/month) has 500,000 premium requests per month (1,000 per user). Their platform team estimates that each developer will assign 2-3 issues per week to the coding agent, consuming approximately 10-15 premium requests per month per developer (including iteration sessions). This represents less than 2% of their total premium request budget, making the coding agent cost-effective even at scale. They set a dedicated SKU budget of 10,000 premium requests per month for the coding agent to monitor adoption and prevent runaway usage during the pilot.
2.7 Limitations and Guardrails
The coding agent is powerful but not unlimited. Understanding its constraints helps enterprise teams set appropriate expectations and choose the right tasks to delegate.
Task scope limitations:
- The agent works best on well-scoped tasks that can be completed in a single PR. Multi-PR epics should be broken into individual issues.
- Tasks requiring access to external systems (databases, APIs, cloud consoles) beyond what is available in the sandbox are not suitable.
- The agent cannot interact with GitHub features beyond creating branches and PRs -- it cannot create issues, close issues, manage projects, or modify repository settings.
Security guardrails:
- The agent can only push to
copilot/prefixed branches - Draft PRs require human approval before workflows run
- The agent cannot approve or merge its own PRs
- The assigning developer cannot approve the PR (in repositories requiring approval)
- The agent has no access to repository secrets until a human approves workflow runs
- Internet access from the sandbox is firewall-controlled
Environment limitations:
- The agent runs only on Ubuntu x64 Linux runners. Windows, macOS, and ARM runners are not supported.
- The sandbox is ephemeral; no state persists between sessions
- Large repositories with extensive build times may approach Actions timeout limits
Quality considerations:
- Complex architectural decisions, large-scale refactoring, and design work should remain with human developers
- The agent may not follow all team conventions without explicit custom instructions
- Generated code should always be reviewed by a human with domain knowledge
2.8 Customizing the Agent Environment: copilot-setup-steps.yml
The copilot-setup-steps.yml file is a GitHub Actions workflow file that configures the agent's development environment before it starts working. This file lives in the .github/workflows/ directory of your repository and is analogous to setting up a development machine for a new team member.
A typical copilot-setup-steps.yml file:
# .github/workflows/copilot-setup-steps.yml
name: "Copilot Setup Steps"
on: workflow_dispatch
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Verify build
run: npm run build
- name: Verify tests pass
run: npm test
Key points about copilot-setup-steps.yml:
- The file runs as a normal GitHub Actions workflow when changes are made, so you can verify it works before the agent uses it
- You can only customize the steps within the
copilot-setup-stepsjob. Other job settings are controlled by GitHub. - The runner must be Ubuntu x64. To use larger runners (for repositories with heavy build requirements), set the
runs-onvalue to your custom runner label. - Once merged into the default branch, you can manually trigger the workflow from the Actions tab to verify it works
For enterprise organizations with standardized build toolchains, the copilot-setup-steps.yml file should mirror the environment setup steps from your CI pipeline. If the agent can build and test the code in its sandbox, it is far more likely to produce quality PRs.
2.9 Custom Instructions for the Coding Agent
Custom instructions tell the agent about your project's conventions, coding standards, architecture decisions, and testing requirements. Without custom instructions, the agent relies solely on what it can infer from the codebase.
The coding agent supports multiple instruction file formats, evaluated in the following order of precedence:
.github/copilot-instructions.md
This is the primary custom instructions file. It applies to all Copilot features in the repository, including the coding agent:
# Project Instructions
## Architecture
This is a Node.js microservice using Express.js and TypeScript.
All source code is in `src/`. Tests are in `tests/`.
## Coding Standards
- Use TypeScript strict mode
- All functions must have JSDoc comments
- Error handling must use custom error classes from `src/errors/`
- No `any` types allowed
## Testing
- Use Jest for unit tests
- Every new function must have corresponding unit tests
- Minimum 80% code coverage required
- Run tests with: `npm test`
## Build
- Build with: `npm run build`
- Lint with: `npm run lint`
.github/instructions/*.instructions.md
For more granular control, you can create multiple instruction files with YAML frontmatter that specifies which files they apply to:
---
applyTo: "src/api/**"
---
# API Layer Instructions
- All API endpoints must validate input using Zod schemas
- Return standardized error responses using `ApiError` class
- Include request ID in all log messages
- Rate limiting is handled by middleware; do not implement in handlers
AGENTS.md
The AGENTS.md file (placed in the repository root) provides instructions specifically for agent-style workflows. You can also create nested AGENTS.md files in subdirectories for context-specific guidance. The coding agent reads AGENTS.md alongside .github/copilot-instructions.md and .github/instructions/ files.
Enterprise Scenario: A 250-developer e-commerce company maintains a monorepo with frontend, backend, and infrastructure code. They create separate instruction files for each domain:
.github/instructions/frontend.instructions.mdscopes tosrc/frontend/**and specifies React conventions,.github/instructions/backend.instructions.mdscopes tosrc/api/**and specifies Go coding standards, and.github/instructions/infra.instructions.mdscopes toterraform/**and specifies module conventions. When the coding agent works on a frontend issue, it receives the frontend-specific instructions automatically.
2.10 Reviewing Agent-Created Pull Requests
Reviewing code produced by the coding agent follows the same process as reviewing any PR, but with additional considerations:
-
Read the PR description carefully: The agent explains its reasoning and approach. This context helps you understand why it made specific choices.
-
Check the linked issue: Verify that the agent's implementation matches the issue requirements. The agent links every PR to its source issue.
-
Review the full diff: Do not skip files. The agent may modify files you did not expect. Use GitHub's file filter to navigate large diffs.
-
Run CI before deep review: Click "Approve and run workflows" early in your review. If CI fails, the agent may need to iterate before your detailed review is worthwhile.
-
Use @copilot mentions for iteration: If you need changes, leave specific, actionable review comments and mention @copilot. The agent will start a new session to address your feedback.
-
Check for common agent patterns:
- Over-engineering: The agent sometimes adds more abstraction than necessary
- Missing edge cases: Verify error handling and boundary conditions
- Style drift: Ensure the code matches your team's conventions (custom instructions help prevent this)
- Test quality: Verify that tests are meaningful, not just achieving coverage numbers
-
Require independent approval: In repositories with branch protection rules requiring approving reviews, the developer who assigned the issue cannot approve the PR. This ensures at least one independent human reviews the agent's work.
2.11 Plans That Support the Coding Agent
The Copilot coding agent is available on the following plans:
- GitHub Copilot Pro ($10/month)
- GitHub Copilot Pro+ ($39/month)
- GitHub Copilot Business ($19/user/month)
- GitHub Copilot Enterprise ($39/user/month)
For Copilot Business and Enterprise subscribers, the agent must be explicitly enabled by an administrator (see Section 2.3). For individual plan subscribers (Pro and Pro+), the agent is available by default.
The Copilot Free tier includes limited access with 50 premium requests per month, which can be used for coding agent sessions.
3. Diagrams
Coding Agent Workflow: From Issue to Merged PR
flowchart TD
A[Developer creates or<br>selects a GitHub Issue] --> B[Assign issue to @copilot]
B --> C[Agent reads issue, repo context,<br>and custom instructions]
C --> D[Agent provisions ephemeral<br>Ubuntu sandbox via GitHub Actions]
D --> E[Run copilot-setup-steps.yml<br>to install dependencies]
E --> F[Agent creates copilot/ branch<br>and writes code]
F --> G{Agent runs build,<br>tests, linters}
G -->|Pass| H[Agent opens Draft PR<br>and requests review]
G -->|Fail| F
H --> I[Human reviews PR diff<br>and leaves comments]
I --> J{Approved?}
J -->|Changes requested<br>@copilot mentioned| K[Agent starts new session<br>with previous context]
K --> F
J -->|Approved| L[Human clicks Approve<br>and run workflows]
L --> M{CI checks pass?}
M -->|Yes| N[Independent reviewer<br>approves PR]
M -->|No| I
N --> O[Human merges PR]
style A fill:#e1f5fe
style B fill:#e1f5fe
style H fill:#fff3e0
style N fill:#c8e6c9
style O fill:#c8e6c9
Figure 13.1: The complete coding agent workflow. Blue nodes represent developer actions, orange represents the agent's output, and green represents the final merge steps. Note the iteration loop between review comments and new agent sessions.
Sandbox Architecture
flowchart LR
subgraph GitHub["GitHub Platform"]
ISS[GitHub Issue<br>assigned to @copilot]
REPO[Repository<br>read-only access]
PR[Draft Pull Request]
ACTIONS[GitHub Actions<br>CI Workflows]
end
subgraph Sandbox["Ephemeral Agent Sandbox"]
direction TB
RUNNER[Ubuntu x64 Runner<br>GitHub Actions infrastructure]
SETUP[copilot-setup-steps.yml<br>dependency installation]
LLM[LLM-powered agent<br>code generation + reasoning]
TOOLS[Build tools, test runners,<br>linters, package managers]
BRANCH["copilot/ branch<br>(push-only target)"]
end
subgraph Security["Security Boundaries"]
FW[Firewall-controlled<br>internet access]
NOSECRETS[No secrets access<br>until human approves workflows]
READONLY[Read-only repo access<br>write only to copilot/ branches]
end
ISS --> RUNNER
REPO --> RUNNER
RUNNER --> SETUP
SETUP --> LLM
LLM --> TOOLS
TOOLS --> BRANCH
BRANCH --> PR
PR -.->|Human approves| ACTIONS
FW -.-> RUNNER
NOSECRETS -.-> RUNNER
READONLY -.-> RUNNER
style GitHub fill:#e3f2fd
style Sandbox fill:#fff3e0
style Security fill:#fce4ec
Figure 13.2: The coding agent sandbox architecture. The agent runs in an ephemeral Ubuntu runner with firewall-controlled internet access. It can only push to copilot/ branches. CI workflows require explicit human approval before executing.
Policy Enablement Flow
flowchart TD
ENT[Enterprise Owner] --> EPOL{Enterprise Policy<br>for Coding Agent}
EPOL -->|Enabled| EALL[All orgs: agent available]
EPOL -->|Disabled| ENONE[All orgs: agent blocked]
EPOL -->|No Policy| OPOL{Organization Owner<br>sets policy}
OPOL -->|Enabled| RPOL{Repository-Level<br>Control}
OPOL -->|Disabled| ONONE[Org members:<br>agent blocked]
RPOL -->|All repos| RALL[Agent available in<br>all org repositories]
RPOL -->|Selected repos| RSOME[Agent available in<br>selected repositories only]
EALL --> USERS[Users with Copilot license<br>can assign issues to @copilot]
RALL --> USERS
RSOME --> USERS
style ENT fill:#e1f5fe
style USERS fill:#c8e6c9
style ENONE fill:#ffcdd2
style ONONE fill:#ffcdd2
Figure 13.3: Policy enablement flow for the Copilot coding agent. Enterprise owners set the top-level policy. When set to "No policy," organization owners make the decision. Repository-level controls provide the finest granularity.
4. Summary
Key Takeaways:
- The Copilot coding agent is GitHub's asynchronous AI developer that reads issues, creates branches, writes code, runs tests, and opens draft pull requests -- all within an ephemeral, sandboxed GitHub Actions environment with firewall-controlled internet access and strict security boundaries.
- Enabling the agent requires explicit policy configuration at the enterprise and organization levels (disabled by default for Business and Enterprise plans). The recommended enterprise rollout strategy uses "No policy" at the enterprise level, letting organizations pilot independently.
- The agent workflow integrates with standard GitHub pull request processes: assign an issue to @copilot, review the draft PR, iterate through @copilot mentions in review comments, approve CI workflows manually, and require an independent reviewer before merging.
- Costs are predictable: each coding agent session consumes one premium request plus GitHub Actions minutes. Enterprise administrators should set dedicated SKU budgets to monitor and control agent usage across organizations.
- Custom instructions via
.github/copilot-instructions.md,.github/instructions/*.instructions.md, andAGENTS.mdfiles are essential for production use. Combined withcopilot-setup-steps.ymlfor environment setup, these files ensure the agent follows your team's conventions and can validate its own work.
What's Next: See Chapter 14: Agent Skills & Custom Agents for how to extend the coding agent with custom agent profiles, Model Context Protocol (MCP) servers, and specialized skills that connect the agent to external tools and services.
5. Hands-On Assignment
Prerequisites Check: Before starting this lab, ensure you have completed:
- Copilot policies configured and coding agent enabled (Chapter 5: Copilot Policies & Content Controls)
- GitHub Actions workflows operational in your repository (Chapter 12: GitHub Actions & CI/CD Workflows)
- An active Copilot Enterprise license (Chapter 4: Copilot Licensing & Plan Management)
Lab: Enable the Coding Agent and Assign Your First Issue
Objective: Enable the Copilot coding agent for your organization, configure the agent development environment for a repository, create a well-scoped issue, assign it to Copilot, and review the resulting pull request.
Prerequisites:
- A GitHub Enterprise Cloud organization with Copilot Business or Enterprise licenses (see Chapter 1: Enterprise Subscription & Environment Setup)
- Organization owner or admin access to configure Copilot policies
- A repository with at least a basic project structure (source code, tests, and a build process)
- The Copilot coding agent policy enabled at the enterprise level (set to "Enabled" or "No policy")
- The GitHub CLI (
gh) installed and authenticated (see Chapter 9: GitHub CLI for Enterprise)
Assignment:
- Enable the Copilot coding agent policy at the organization level. Verify that the policy is active and that MCP servers are also enabled.
- Create a
copilot-setup-steps.ymlfile in the.github/workflows/directory of your target repository. The file should install your project's dependencies and verify that the build and test commands succeed. - Create a
.github/copilot-instructions.mdfile with at least three instructions covering your project's coding standards, testing requirements, and build commands. - Create a well-scoped GitHub issue suitable for the coding agent. The issue should include a clear title, description, specific requirements, and acceptance criteria.
- Assign the issue to @copilot and observe the agent's progress.
- When the agent opens a draft PR, review the code, leave at least one review comment mentioning @copilot to request a change, and verify that the agent iterates on your feedback.
- Approve and run the CI workflows. Verify that checks pass. If an independent reviewer is available, have them approve the PR.
Expected Outcome: You should have the coding agent enabled in your organization, a repository configured with setup steps and custom instructions, and a completed agent-generated pull request that has been reviewed, iterated on, and is ready to merge.
Validation:
- The Copilot coding agent policy shows as "Enabled" in organization settings
- The
copilot-setup-steps.ymlworkflow runs successfully when triggered manually - The
.github/copilot-instructions.mdfile is committed to the default branch - A draft PR from a
copilot/branch exists, linked to your issue - The PR timeline shows at least one iteration cycle (review comment followed by new agent commits)
- CI workflows have been approved and passed
6. Step-by-Step Walkthrough
This section provides a guided solution for the hands-on assignment above. If you completed the assignment independently, you can skip this section or use it to verify your approach.
Step 1: Enable the Coding Agent Policy
Navigate to your organization's Copilot policy settings:
- Open
https://github.com/organizations/YOUR-ORG/settings/copilot/policies - Scroll to the Copilot coding agent section
- Select Enabled from the dropdown
- Scroll to the MCP servers on GitHub.com section
- Select Enabled from the dropdown
- Click Save
Verify the policy using the GitHub CLI:
# Verify organization Copilot settings (bash)
gh api orgs/YOUR-ORG/copilot/billing --jq '{seat_management_setting, copilot_chat}'
Expected output (fields will vary by plan):
{
"seat_management_setting": "assign_selected",
"copilot_chat": "enabled"
}
Step 2: Create the copilot-setup-steps.yml File
For a Node.js project, create the following file. Adapt the steps for your project's language and build system.
Create the file at .github/workflows/copilot-setup-steps.yml:
# .github/workflows/copilot-setup-steps.yml
name: "Copilot Setup Steps"
on: workflow_dispatch
jobs:
copilot-setup-steps:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: "20"
cache: "npm"
- name: Install dependencies
run: npm ci
- name: Verify build succeeds
run: npm run build
- name: Verify tests pass
run: npm test
- name: Verify linting passes
run: npm run lint
Commit and push the file:
# Create the workflow file and commit (bash)
git add .github/workflows/copilot-setup-steps.yml
git commit -m "Add copilot-setup-steps.yml for coding agent environment"
git push origin main
Verify the workflow runs successfully:
# Trigger the workflow manually (bash)
gh workflow run "Copilot Setup Steps" --repo YOUR-ORG/YOUR-REPO
# Watch the workflow run
gh run list --workflow="Copilot Setup Steps" --repo YOUR-ORG/YOUR-REPO --limit 1
Expected output:
STATUS TITLE WORKFLOW BRANCH EVENT ID ELAPSED AGE
✓ Copilot Setup Steps Copilot Setup Steps main workflow_dispatch 1234567890 2m30s 1m
Step 3: Create Custom Instructions
Create the file .github/copilot-instructions.md in your repository:
# Project Instructions for Copilot
## Project Overview
This is a Node.js REST API built with Express.js and TypeScript.
## Build and Test
- Install dependencies: `npm ci`
- Build the project: `npm run build`
- Run tests: `npm test`
- Run linter: `npm run lint`
## Coding Standards
- Use TypeScript strict mode for all new files
- All exported functions must have JSDoc documentation
- Use async/await instead of raw Promises
- Handle errors using the custom `AppError` class from `src/errors/`
## Testing Requirements
- Write unit tests for every new function
- Place test files adjacent to source files with `.test.ts` suffix
- Use Jest as the test framework
- Mock external dependencies using Jest mocks
- Aim for meaningful test coverage, not just line coverage
## Git Conventions
- Write clear, descriptive commit messages
- Reference the issue number in commit messages
Commit and push:
# Commit the custom instructions file (bash)
git add .github/copilot-instructions.md
git commit -m "Add custom instructions for Copilot coding agent"
git push origin main
Step 4: Create a Well-Scoped Issue
Create an issue using the GitHub CLI:
# Create an issue for the coding agent (bash)
gh issue create \
--repo YOUR-ORG/YOUR-REPO \
--title "Add health check endpoint to API" \
--body "## Description
The API currently has no health check endpoint for load balancer integration.
We need a simple \`GET /health\` endpoint that returns the service status.
## Requirements
- Create a new route handler at \`GET /health\`
- Return JSON: \`{ \"status\": \"ok\", \"timestamp\": \"<ISO-8601>\" }\`
- Response must return HTTP 200
- No authentication required on this endpoint
- Add unit tests for the health check handler
## Acceptance Criteria
- [ ] GET /health returns 200 with correct JSON structure
- [ ] Timestamp is a valid ISO-8601 string
- [ ] Unit tests cover the happy path
- [ ] Existing tests still pass
- [ ] Code passes linting"
Expected output:
Creating issue in YOUR-ORG/YOUR-REPO
https://github.com/YOUR-ORG/YOUR-REPO/issues/42
Step 5: Assign the Issue to Copilot
Assign the issue to Copilot using the GitHub web interface or CLI:
Using the web interface:
- Open the issue at
https://github.com/YOUR-ORG/YOUR-REPO/issues/42 - In the right sidebar, click Assignees
- Type copilot and select @copilot from the dropdown
- The agent begins working immediately
Using the GitHub CLI:
# Assign the issue to Copilot (bash)
gh issue edit 42 --repo YOUR-ORG/YOUR-REPO --add-assignee @copilot
After assignment, you will see activity on the issue indicating that Copilot has started working. The agent typically takes 3-15 minutes depending on the complexity of the task and the size of the repository.
Step 6: Review and Iterate on the Agent's PR
Once the agent opens a draft PR, you will receive a notification. Open the PR and review the changes:
# List recent PRs to find the agent's PR (bash)
gh pr list --repo YOUR-ORG/YOUR-REPO --author app/copilot --state open
Expected output:
Showing 1 of 1 pull request in YOUR-ORG/YOUR-REPO
#43 Add health check endpoint to API copilot/add-health-check about 5 minutes ago
Review the PR:
# View the PR details (bash)
gh pr view 43 --repo YOUR-ORG/YOUR-REPO
# View the diff (bash)
gh pr diff 43 --repo YOUR-ORG/YOUR-REPO
To request a change and trigger the agent to iterate, leave a review comment:
- Open the PR in the web interface
- Click Review changes or add a comment on a specific line
- Write your feedback, for example: "@copilot Please also add a
versionfield to the health check response that reads frompackage.json." - Submit the review as Request changes
The agent will start a new session, read your feedback, and push additional commits addressing your request. You will see new commits appear on the PR within a few minutes.
Step 7: Approve Workflows and Merge
Once you are satisfied with the code:
- On the PR page, click "Approve and run workflows" in the merge box area. This allows your CI pipeline (configured in Chapter 12: GitHub Actions & CI/CD Workflows) to execute on the agent's code.
- Wait for all CI checks to complete.
- If you have an independent reviewer available, ask them to review and approve the PR.
- Merge the PR using your preferred strategy:
# Merge the PR with squash strategy (bash)
gh pr merge 43 --repo YOUR-ORG/YOUR-REPO --squash --delete-branch
Expected output:
✓ Squashed and merged pull request #43 (Add health check endpoint to API)
✓ Deleted branch copilot/add-health-check
Verification
Run the following commands to confirm all lab objectives are met:
# 1. Verify the coding agent policy is enabled
# (Check in web UI: https://github.com/organizations/YOUR-ORG/settings/copilot/policies)
# 2. Verify the setup steps workflow exists and has run successfully
gh run list --workflow="Copilot Setup Steps" --repo YOUR-ORG/YOUR-REPO --limit 1
# 3. Verify the custom instructions file exists
gh api repos/YOUR-ORG/YOUR-REPO/contents/.github/copilot-instructions.md --jq '.name'
# 4. Verify the issue was assigned to Copilot and is now closed
gh issue view 42 --repo YOUR-ORG/YOUR-REPO --json state,assignees --jq '{state, assignees: [.assignees[].login]}'
# 5. Verify the PR was merged
gh pr view 43 --repo YOUR-ORG/YOUR-REPO --json state,mergedAt --jq '{state, mergedAt}'
Expected output for verification step 5:
{
"state": "MERGED",
"mergedAt": "2026-02-01T15:30:00Z"
}
7. Q&A -- Chapter Review
Instructions: Select the best answer for each question. Answers and explanations follow after all questions.
Question 1
What type of environment does the Copilot coding agent use to execute its work?
- A) The developer's local machine via a remote connection
- B) A persistent virtual machine managed by the organization's IT team
- C) An ephemeral GitHub Actions runner with a sandboxed Ubuntu x64 environment
- D) A Docker container running on the organization's self-hosted runners
Question 2
A developer assigns a GitHub issue to the Copilot coding agent. Which branch naming pattern will the agent use for its work?
- A)
feature/copilot-<issue-number> - B)
copilot/<descriptive-slug> - C)
agent/<issue-number>-<title> - D)
auto/<timestamp>-<issue-number>
Question 3
An enterprise owner wants to allow individual organization owners to decide whether to enable the coding agent for their teams. Which enterprise-level policy setting should they choose?
- A) Enabled
- B) Disabled
- C) No policy
- D) Delegated
Question 4
After the Copilot coding agent opens a draft pull request, what must happen before GitHub Actions CI workflows can execute on the agent's code?
- A) The agent must mark the PR as "Ready for review"
- B) A user with write permissions must click "Approve and run workflows"
- C) The organization owner must approve the workflow run in the Actions settings
- D) The CI workflows run automatically as soon as the PR is opened
Question 5
How many premium requests does a single Copilot coding agent session consume?
- A) One premium request per file modified
- B) One premium request per commit pushed
- C) One premium request per session, regardless of complexity
- D) Premium requests are not consumed; only GitHub Actions minutes are used
Question 6
A team wants to ensure the coding agent installs Node.js 20, runs npm ci, and verifies the build before starting work on code changes. Which file should they create?
- A)
.github/copilot-instructions.md - B)
.github/workflows/copilot-setup-steps.yml - C)
.github/workflows/agent-environment.yml - D)
AGENTS.md
Question 7
Which of the following tasks is the Copilot coding agent NOT able to perform?
- A) Creating a new branch and pushing commits
- B) Opening a draft pull request with a description
- C) Approving and merging its own pull request
- D) Running build commands and tests in its sandbox
Question 8
A developer submits a review on a coding agent PR with three comments requesting changes. How should they trigger the agent to address the feedback?
- A) Close the PR and reassign the original issue to @copilot
- B) Mention @copilot in the review comments and submit the review as "Request changes"
- C) Push commits to the copilot/ branch directly
- D) Edit the original issue with updated requirements
Question 9
An enterprise administrator wants to provide different coding standards to the Copilot coding agent for the frontend and backend directories of a monorepo. Which custom instructions approach supports this?
- A) Create a single
.github/copilot-instructions.mdfile with all standards combined - B) Create separate files under
.github/instructions/withapplyTofrontmatter targeting specific directories - C) Create separate
AGENTS.mdfiles in each directory but remove.github/copilot-instructions.md - D) Configure per-directory settings in
copilot-setup-steps.yml
Question 10
In a repository where branch protection rules require an approving review before merging, which statement about Copilot coding agent PRs is correct?
- A) The agent can approve its own PR if all CI checks pass
- B) The developer who assigned the issue to Copilot can approve the resulting PR
- C) The developer who assigned the issue cannot approve the PR; an independent reviewer is required
- D) Branch protection rules are automatically bypassed for agent-created PRs
Answer Key
| Q | Answer | Explanation |
|---|---|---|
| 1 | C | The Copilot coding agent runs in an ephemeral Ubuntu x64 runner powered by GitHub Actions infrastructure. The sandbox is destroyed after each session, and no state persists between sessions. |
| 2 | B | The coding agent can only create and push to branches prefixed with copilot/. It generates a descriptive slug based on the issue content, producing branches like copilot/fix-login-timeout. |
| 3 | C | Setting the enterprise policy to "No policy" delegates the decision to individual organization owners, allowing each organization to enable or disable the coding agent independently based on their readiness and risk profile. |
| 4 | B | GitHub Actions workflows do not run automatically on agent-created draft PRs. A user with write permissions must explicitly click "Approve and run workflows" to allow CI pipelines to execute, preventing the agent from accessing repository secrets without human oversight. |
| 5 | C | Each coding agent session consumes exactly one premium request, regardless of the number of files modified or the complexity of the task. GitHub Actions minutes are consumed separately based on session duration. |
| 6 | B | The copilot-setup-steps.yml file in .github/workflows/ configures the agent's development environment by installing dependencies, setting up runtimes, and verifying build and test commands before the agent begins writing code. |
| 7 | C | The coding agent cannot approve or merge its own pull requests. It also cannot mark PRs as "Ready for review." Every merge requires explicit human approval, ensuring that a human always reviews and authorizes agent-produced code. |
| 8 | B | Mentioning @copilot in review comments triggers a new agent session. The agent reads the feedback (with context from the previous session) and pushes new commits addressing the requested changes. Batching comments into a single review is recommended for efficiency. |
| 9 | B | Files under .github/instructions/ support YAML frontmatter with an applyTo field that specifies glob patterns for the files or directories the instructions apply to. This enables directory-specific coding standards in monorepos. |
| 10 | C | The developer who assigned the issue to Copilot cannot approve the resulting PR in repositories that require an approving review. This ensures at least one independent human developer reviews the agent's work before it can be merged. |