elastic / elastic/ai-github-actions
[information-architecture] Required COPILOT_GITHUB_TOKEN prerequisite is detached from per-workflow Quick install paths
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Information Architecture Findings
### 1. Required authentication prerequisite is separated from the pages users install from
**Area:** Action placement / Progressive disclosure
**Component(s):**
- `docs/workflows/gh-agent-workflows/issue-triage.md` (Quick install at lines 7-13)
- `docs/workflows/gh-agent-workflows/pr-review.md` (Quick install at lines 7-13)
- `docs/workflows/gh-agent-workflows/mention-in-issue.md` (Quick install at lines 7-13)
- `docs/workflows/gh-agent-workflows.md` (global `COPILOT_GITHUB_TOKEN` prerequisite at lines 130-141)
- `mkdocs.yml` (navigation routes directly to individual workflow pages, lines 31-35)
- `docs/workflows/gh-agent-workflows/estc-pr-buildkite-detective.md` (`Required secrets` shown locally, lines 40-44)
**Problem:** Several primary workflow pages start with a direct "Quick install" snippet, but do not place the required `COPILOT_GITHUB_TOKEN` setup near that action. The token requirement is documented on a separate overview page, so users arriving via direct nav to a workflow page can complete the visible install step but still fail at runtime due to missing auth. This breaks expected action flow (prerequisite next to action) and creates onboarding confusion.
**Suggested improvement:** Add a standardized "Required secrets" prerequisite block immediately under the Quick install section on workflow pages that need `COPILOT_GITHUB_TOKEN` (or a prominent reusable include/callout in the same location), with a direct link to the canonical token setup steps.
## Suggested Actions
- [ ] Add a shared prerequisite snippet (or include) for `COPILOT_GITHUB_TOKEN` and place it directly below Quick install in affected workflow docs.
- [ ] Audit workflow pages reachable from the main nav to ensure required secrets are shown in-page before install/configuration steps.
- [ ] Keep the overview Secrets section as canonical detail, but ensure each page-local setup path exposes required prerequisites inline.
> [!NOTE]
>
> 🔒 Integrity filter blocked 2 items
>
> The following items were blocked because they don't meet the GitHub integrity level.
>
> - elastic/ai-github-actions#704 `list_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
> - [#704](https://github.com/elastic/ai-github-actions/issues/704) `search_issues`: has lower integrity than agent requires. The agent cannot read data with integrity below "approved".
>
> To allow these resources, lower `min-integrity` in your GitHub frontmatter:
>
> ```yaml
> tools:
> github:
> min-integrity: approved # merged | approved | unapproved | none
> ```
>
>
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/24736691007)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.