elastic / elastic/ai-github-actions

[information-architecture] Required COPILOT_GITHUB_TOKEN prerequisite is detached from per-workflow Quick install paths

Open
#993 0 comments 0 reactions 0 assignees View on GitHub
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

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.