elastic / elastic/ai-github-actions
[information-architecture] Core workflow pages inconsistently surface required secret setup
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Information Architecture Findings
### 1. Required secret setup is inconsistently placed across core workflow pages
**Area:** Consistency
**Component(s):** `docs/index.md`, `docs/workflows/gh-agent-workflows/issue-triage.md`, `docs/workflows/gh-agent-workflows/mention-in-issue.md`, `docs/workflows/gh-agent-workflows/mention-in-pr.md`, `docs/workflows/gh-agent-workflows/pr-review.md`, `docs/workflows/gh-agent-workflows/pr-actions-detective.md`, `docs/workflows/gh-agent-workflows.md`
**Problem:** Users enter the five core workflows from `docs/index.md`, but only one of those workflow pages has a dedicated **Secrets** section. The other core pages place the required `COPILOT_GITHUB_TOKEN` only inside the YAML example block. This makes a required prerequisite easy to miss and creates an inconsistent setup flow across equivalent pages.
**Evidence:**
- Core entry points are grouped together in one onboarding surface: `docs/index.md:48-58`.
- `Issue Triage` explicitly exposes prerequisites with a dedicated section: `docs/workflows/gh-agent-workflows/issue-triage.md:32-37`.
- `Mention in Issue` has no Secrets section; required token appears only in example YAML: `docs/workflows/gh-agent-workflows/mention-in-issue.md:31-37`, `docs/workflows/gh-agent-workflows/mention-in-issue.md:58-59`.
- `Mention in PR` has no Secrets section; required token appears only in example YAML: `docs/workflows/gh-agent-workflows/mention-in-pr.md:32-40`, `docs/workflows/gh-agent-workflows/mention-in-pr.md:63-64`.
- `PR Review` has no Secrets section; required token appears only in example YAML: `docs/workflows/gh-agent-workflows/pr-review.md:33-39`, `docs/workflows/gh-agent-workflows/pr-review.md:58-59`.
- `PR Actions Detective` has no Secrets section; required token appears only in example YAML: `docs/workflows/gh-agent-workflows/pr-actions-detective.md:34-40`, `docs/workflows/gh-agent-workflows/pr-actions-detective.md:60-61`.
- The global secrets guidance exists elsewhere in the catalog page, not in each core page: `docs/workflows/gh-agent-workflows.md:130-143`.
**Suggested improvement:** Add a consistent per-page **Secrets** (or **Prerequisites**) section for every core workflow page, placed before the example YAML, and explicitly list required vs optional secrets.
## Suggested Actions
- [ ] Add a standardized **Secrets/Prerequisites** section template to all five core workflow docs.
- [ ] Keep the example YAML `secrets:` block, but reference the section directly above so required setup is not hidden in code.
- [ ] Add a docs consistency check (or review checklist item) ensuring core workflow pages expose required secrets in the same location/structure.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/26592912527)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Assessment
This issue has not been assessed yet.