Skip to content

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

Closed

Description

@github-actions

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 #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 -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions