Document bots field in frontmatter reference

[Copilot]

The bots field is implemented, tested, and used in production workflows but has no documentation in the frontmatter reference.

Changes

• Added bots documentation section in docs/src/content/docs/reference/frontmatter.md
  • Placed after roles: section (both are access control features)
  • Includes YAML example, behavior details, and common bot names
  • Explains interaction with roles: field and trigger enforcement

Example

bots: 
  - "dependabot[bot]"
  - "renovate[bot]"
  - "agentic-workflows-dev[bot]"

When specified, only listed bot accounts (if active/installed on the repository) can trigger the workflow. Works with roles: for comprehensive access control.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Code Quality] Add documentation for undocumented bots field in frontmatter</issue_title>
<issue_description>## Description

The bots field is fully implemented, tested, and used in production workflows but has no documentation in the frontmatter reference.

Current Status

• ✅ Schema: Defined in properties.bots (array of strings)
• ✅ Tests: Comprehensive tests in pkg/workflow/bots_test.go
• ✅ Usage: Multiple workflows use bots: ["agentic-workflows-dev[bot]"]
• ❌ Documentation: Missing from docs/src/content/docs/reference/frontmatter.md

Impact

Users cannot discover or use this security feature without reading source code or examples. This is a valuable access control feature that should be documented.

Suggested Changes

Add a dedicated section in docs/src/content/docs/reference/frontmatter.md:

### Bot Filtering (`bots:`)

Configure which GitHub bot accounts can trigger workflows. Useful for allowing specific automation bots while maintaining security controls.

``````yaml
bots: 
  - "dependabot[bot]"
  - "renovate[bot]"
  - "agentic-workflows-dev[bot]"

Behavior:

• When specified, only the listed bot accounts can trigger the workflow
• Combine with roles: for comprehensive access control
• Applies to all workflow triggers (pull_request, issues, etc.)

## Files Affected

- `docs/src/content/docs/reference/frontmatter.md` (add new section)

## Success Criteria

- `bots:` field is documented with clear examples
- Users understand when and how to use bot filtering
- Documentation explains interaction with `roles:` field
- Examples show common bot names

## Source

Extracted from [Schema Consistency Audit discussion github/gh-aw#13424](https://github.com/github/gh-aw/discussions/13424) - identified as **Medium Severity** documentation gap.

## Priority

**Medium** - Security/access control feature with good implementation but zero documentation


<!-- gh-aw-tracker-id: discussion-task-miner -->




> AI generated by [Discussion Task Miner - Code Quality Improvement Agent](https://github.com/github/gh-aw/actions/runs/21623941328)
> - [x] expires <!-- gh-aw-expires: 2026-02-17T09:11:54.449Z --> on Feb 17, 2026, 9:11 AM UTC

<!-- gh-aw-agentic-workflow: Discussion Task Miner - Code Quality Improvement Agent, gh-aw-tracker-id: discussion-task-miner, engine: copilot, run: https://github.com/github/gh-aw/actions/runs/21623941328 -->

<!-- gh-aw-workflow-id: discussion-task-miner --></issue_description>

## Comments on the Issue (you are @copilot in this section)

<comments>
</comments>

• Fixes [Code Quality] Add documentation for undocumented bots field in frontmatter #13436

---

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

[Copilot]

Pull request overview

This pull request adds documentation for the previously undocumented bots field in the frontmatter reference. The field is fully implemented, tested, and used in production workflows but lacked user-facing documentation.

Changes:

• Added comprehensive documentation for the bots: field in frontmatter reference
• Placed after roles: section to group related access control features
• Includes behavior details, YAML examples, and common bot names

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.