elastic / elastic/ai-github-actions

[information-architecture] Core workflow pages inconsistently surface required secret setup

Open
#1,185 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 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

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.