Add Copilot agent manifest and usage documentation

[Copilot]

Configures GitHub Copilot coding agent with conservative permissions for automated PR workflows. Enables agent to modify source/test files while requiring human review before merge.

Changes

• .github/agents/copilot-agent.yml: Agent manifest with scoped permissions

  • Write access limited to src/**/*, tests/**/*, README.md, AGENTS.md
  • Enforces review gate: require_review_before_merge: true, required_approvals: 1
  • Allows squash/merge strategies, disables auto-merge, enables workflow execution
  • Documents admin prerequisites: app installation and repo permissions (contents, PRs, checks, actions, issues: write)

• AGENTS.md: Agent instruction reference

  • Instruction channels: PR front-matter YAML, slash commands (/copilot run), labels
  • Configuration examples and recommended labels (copilot: run, copilot: approve)
  • Admin setup steps and governance controls

Admin Action Required

After merge, repository admin must:

1. Install GitHub Copilot coding agent app
2. Grant repository permissions matching manifest scope
3. Verify Actions enabled and branch protections compatible

Original prompt

Create a new branch named copilot-agent-config-and-docs and open a pull request against master that adds/updates the repository agent manifest and adds AGENTS.md to document how to request agent actions.

Files to add/update (only under .github, do not change source files):

1. .github/agents/copilot-agent.yml

• Update or create a manifest that enables the copilot-coding-agent and grants it conservative-but-functional permissions to create branches, modify files under src/ and tests/, open and update PRs, and run workflows. Include safety controls like require_review_before_merge: true and required_approvals: 1. Include notes documenting that repository admin must install/authorize the Copilot coding agent app and grant matching permissions.

Contents (exact):

enabled: true
agent:
name: copilot-coding-agent
allow:
- paths: ["src//*", "tests//*", "README.md", "AGENTS.md"]
actions: ["create", "modify", "delete"]
require_review_before_merge: true
required_approvals: 1
allowed_merge_strategies:
- squash
- merge
auto_merge_on_green: false
run_workflows: true
notes: |

• This manifest expresses the policy for the Copilot coding agent in this repository.
• It does NOT install or authorize the agent; a repository admin must install the Copilot coding agent app and grant the repository the necessary permissions (contents: write, pull_requests: write, checks: write, actions: write/read, issues: write) to allow the agent to act.
• Keep allow paths narrow and prefer require_review_before_merge during initial rollout.

2. AGENTS.md (at repository root)

• Add a markdown document that explains how to request agent actions, supported instruction channels (PR front-matter YAML, slash commands in PR comments, labels), examples, safety notes, and how to enable the agent.

Contents (exact):

Agent usage and commands

This document explains how maintainers and contributors can instruct the GitHub Copilot coding agent in this repository.

Supported instruction channels

• PR front-matter (YAML at top of PR body) — preferred for reproducibility.
• PR comment using slash-style commands (e.g. /copilot run apply-fixes).
• Add a label that triggers a run (e.g. copilot: run).

Example PR front-matter (place at the top of the PR body):

copilot:
  run: "apply-fixes"
  target_branch: "master"
  auto_merge: false
  run_tests: true
  required_approvals: 1

Example slash command via PR comment:

• /copilot run apply-fixes --target=master --run-tests

Recommended labels

• copilot: run -> instructs agent to run its default task on the PR
• copilot: approve -> if allowed by policy, agent may merge once checks pass

How to enable and grant permissions

1. Merge .github/agents/copilot-agent.yml into master.
2. As a repository administrator, install/authorize the GitHub Copilot coding agent app and grant it repository permissions that match the manifest (Contents: write, Pull requests: write, Checks: write, Actions: write/read, Issues: write).
3. Ensure Actions is enabled for the repository and branch protection rules are compatible with the manifest (or allow the agent to have the bypass when appropriate).

Safety & governance

• Keep allow paths narrow — only grant the agent write access where it needs it.
• Prefer require_review_before_merge: true during initial rollout.
• Use audit logs to review agent activity and require a human reviewer until you trust the automation.

PR details

• Branch name: copilot-agent-config-and-docs
• Changes: add/modify .github/agents/copilot-agent.yml and add AGENTS.md at repo root
• This PR is intentionally limited to configuration and documentation; it does not add any workflows that push changes or perform merges.

If the repository settings or installed apps block the agent from running, include a clear note in the PR description describing actions an admin must take: enable Actions, install Copilot coding agent app, grant repo write permissions to agent, or run onboarding steps.

Author: GitHub Copilot (@copilot) acting on behalf of adamhathcock.

This pull request was created as a result of the following prompt from Copilot chat.

Create a new branch named copilot-agent-config-and-docs and open a pull request against master that adds/updates the repository agent manifest and adds AGENTS.md to document how to request agent actions.

Files to add/update (only under .github, do not change source files):

1. .github/agents/copilot-agent.yml

• Update or create a manifest that enables the copilot-coding-agent and grants it conservative-but-functional permissions to create branches, modify files under src/ and tests/, open and update PRs, and run workflows. Include safety controls like require_review_before_merge: true and required_approvals: 1. Include notes documenting that repository admin must install/authorize the Copilot coding agent app and grant matching permissions.

Contents (exact):

enabled: true
agent:
name: copilot-coding-agent
allow:
- paths: ["src//*", "tests//*", "README.md", "AGENTS.md"]
actions: ["create", "modify", "delete"]
require_review_before_merge: true
required_approvals: 1
allowed_merge_strategies:
- squash
- merge
auto_merge_on_green: false
run_workflows: true
notes: |

• This manifest expresses the policy for the Copilot coding agent in this repository.
• It does NOT install or authorize the agent; a repository admin must install the Copilot coding agent app and grant the repository the necessary permissions (contents: write, pull_requests: write, checks: write, actions: write/read, issues: write) to allow the agent to act.
• Keep allow paths narrow and prefer require_review_before_merge during initial rollout.

2. AGENTS.md (at repository root)

• Add a markdown document that explains how to request agent actions, supported instruction channels (PR front-matter YAML, slash commands in PR comments, labels), examples, safety notes, and how to enable the agent.

Contents (exact):

Agent usage and commands

This document explains how maintainers and contributors can instruct the GitHub Copilot coding agent in this repository.

Supported instruction channels

• PR front-matter (YAML at top of PR body) — preferred for reproducibility.
• PR comment using slash-style commands (e.g. /copilot run apply-fixes).
• Add a label that triggers a run (e.g. copilot: run).

Example PR front-matter (place at the top of the PR body):

copilot:
  run: "apply-fixes"
  target_branch: "master"
  auto_merge: false
  run_tests: true
  required_approvals: 1

Example slash command via PR comment:

• /copilot run apply-fixes --target=master --run-tests

Recommended labels

• copilot: run -> instructs agent to run its default task on the PR
• copilot: approve -> if allowed by policy, agent may merge once checks pass

How to enable and grant permissions

1. Merge .github/agents/copilot-agent.yml into master.
2. As a repository administrator, install/authorize the GitHub Copilot coding agent app and grant it repository permissions that match the manifest (Contents: write, Pull requests: write, Checks: write, Actions: write/read, Issues: write).
3. Ensure Actions is enabled for the repository and branch protection rules are compatible with the manifest (or allow the agent to have the bypass when appropriate).

Safety & governance

• Keep allow paths narrow — only grant the agent write access where it needs it.
• Prefer require_review_before_merge: true during initial rollout.
• Use audit logs to review agent activity and require a human reviewer until you trust the automation.

PR details

• Branch name: copilot-agent-config-and-docs
• Changes: add/modify .github/agents/copilot-agent.yml and add AGENTS.md at repo root
• This PR is intentionally limited to configuration and documentation; it does not add any workflows that push changes or perform merges.

If the repository settings or installed apps block the agent from running, include a clear note in the PR description describing actions an admin must take: enable Actions, install Copilot coding agent app, grant repo write permissions to agent, or run onboarding steps.

Author: GitHub Copilot (@copilot) acting on behalf of adamhathcock.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.