elastic / elastic/ai-github-actions
[information-architecture] Issue Triage docs place GH_AW_GITHUB_TOKEN under `with` instead of `secrets`
- Dominant language
- Python
- Stars
- 11
- Forks
- 16
- Avg merge
- 22h 9m
- Merged PRs (30d)
- 31
Description
## Information Architecture Findings
### 1. `GH_AW_GITHUB_TOKEN` is shown in the wrong configuration block
**Area:** Action placement
**Component(s):**
- `docs/workflows/gh-agent-workflows/issue-triage.md`
- `gh-agent-workflows/issue-triage/example.yml`
**Problem:** The Issue Triage docs describe `GH_AW_GITHUB_TOKEN` as a secret, but the docs example places it under the commented `with:` block. Users following the docs are likely to put the token in the wrong place, which makes setup flow inconsistent and obscures where this control belongs.
**Evidence:**
- `docs/workflows/gh-agent-workflows/issue-triage.md:33-38` documents `GH_AW_GITHUB_TOKEN` in the **Secrets** table.
- `docs/workflows/gh-agent-workflows/issue-triage.md:62-73` shows `GH_AW_GITHUB_TOKEN` inside the commented `with:` section (no `secrets:` block in that snippet).
- `gh-agent-workflows/issue-triage/example.yml:24-29` shows the same token under a commented `#secrets:` block, which is the expected placement.
**Suggested improvement:** In `docs/workflows/gh-agent-workflows/issue-triage.md`, move the token example lines into a commented `secrets:` block directly below `with:` to match the actual example file and reduce setup ambiguity.
## Suggested Actions
- [ ] Update the Issue Triage docs snippet so `GH_AW_GITHUB_TOKEN` is shown under `secrets:` instead of `with:`.
- [ ] Keep the docs snippet aligned with `gh-agent-workflows/issue-triage/example.yml` for ongoing consistency.
## Duplicate check
This finding is distinct from previously filed IA issues in `/tmp/previous-findings.json` (which focus on taxonomy/discovery grouping and missing workflow discovery). This report is specifically about misplacement of a secret control within the Issue Triage configuration example.
---
[What is this?](https://ela.st/github-ai-tools) | [From workflow: Trigger Information Architecture](https://github.com/elastic/ai-github-actions/actions/runs/30934542486)
Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.
Contributor guide
Research direction
Read docs/workflows/gh-agent-workflows/issue-triage.md around lines 33–38 and 62–73, then compare it with gh-agent-workflows/issue-triage/example.yml around lines 24–29. Confirm that the documentation’s configuration example matches the example file, with GH_AW_GITHUB_TOKEN represented in the appropriate block. Done means the docs no longer place this secret under with and the two examples are consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100