elastic / elastic/ai-github-actions

[information-architecture] Docs workflow pages hide `allowed-bot-users` input present in workflow READMEs

Open
#1,908 0 comments 0 reactions 0 assignees View on GitHub
information-architecture
Dominant language
Python
Stars
11
Forks
16
Avg merge
22h 9m
Merged PRs (30d)
31

Description

## Information Architecture Findings

### 1. Workflow docs split required configuration context across two entry points
**Area:** Consistency
**Component(s):**
- `docs/workflows/gh-agent-workflows/bugs.md` (Inputs table at lines 44-49)
- `gh-agent-workflows/bug-hunter/README.md` (Inputs table at lines 30-35)
- `docs/workflows/gh-agent-workflows/code-duplication.md` (Inputs table at lines 42-50)
- `gh-agent-workflows/code-duplication-detector/README.md` (Inputs table at lines 30-35)
- `docs/workflows/gh-agent-workflows/docs-patrol-overview.md` (Inputs table at lines 42-47)
- `gh-agent-workflows/docs-patrol/README.md` (Inputs table at lines 30-34)

**Problem:** The docs-site workflow pages present an "Inputs" table but omit `allowed-bot-users`, while the corresponding per-workflow README includes it. A user entering from the docs site sees an apparently complete input list and misses the actor-allowlist control entirely, then must discover it through a second, less obvious doc surface (`gh-agent-workflows/*/README.md`). This creates a navigation/structure mismatch where similar setup information is split inconsistently across parallel documentation paths.

**Suggested improvement:** Keep the docs-site and per-workflow README input tables structurally aligned for shared controls (including `allowed-bot-users`), or explicitly indicate on docs-site pages that the table is partial and link directly to the canonical full input matrix.

## Suggested Actions
- [ ] Standardize input-table generation so shared inputs (for example `allowed-bot-users`) appear consistently on both docs-site workflow pages and `gh-agent-workflows/*/README.md`.
- [ ] Add a docs-level convention check that flags when a docs/workflows page input table diverges from its paired workflow README input list.

---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/32876534673)

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.