docs: improve onboarding docs for Elastic employees#36
Conversation
- Add COPILOT_GITHUB_TOKEN secrets section to gh-agent-workflows README - Add comparison table explaining when to use each approach (README.md) - Add inline comments explaining contents: read in RWX examples - Update all claude-workflows paths from workflows/ to claude-workflows/ - Note trigger keyword difference (@claude vs /ai) in SECURITY.md - Add private vulnerability reporting link in SECURITY.md - Clarify make setup tools in DEVELOPING.md - Add claude-workflows scope note to CODE_STYLE.md Addresses #20 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
github-actions
bot
added
the
documentation
|
❌ Author of the following commits did not sign a Contributor Agreement: Please, read and sign the above mentioned agreement if you want to contribute to this project |
|
/ai please review |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Excellent documentation improvements! The changes successfully address the onboarding gaps from issue #31:
✅ High-impact additions — Added critical COPILOT_GITHUB_TOKEN setup documentation with clear step-by-step instructions (gh-agent-workflows/README.md) and comparison table explaining the key differences between approaches (README.md)
✅ Clarity improvements — Added inline security comments to RWX examples, clarified trigger keywords in SECURITY.md, and updated all example paths to match the actual directory structure
✅ Correctness — All technical content is accurate except for one minor wording issue in claude-workflows/README.md (see inline comment)
One NITPICK-level issue flagged inline regarding the backwards compatibility note. Otherwise ready to merge — these changes will significantly improve the Elastic employee onboarding experience.
| Composite GitHub Actions wrapping [Claude Code](https://github.com/anthropics/claude-code-action). Consumed via `uses:` in standard GitHub Actions YAML. | ||
|
|
||
| > **Note:** This directory was renamed from `workflows/` to `claude-workflows/`. A symlink ensures backwards compatibility — existing `uses: elastic/ai-github-actions/workflows/...@v0` references continue to work. | ||
| > **Note:** This directory was renamed from `workflows/` to `claude-workflows/`. A symlink ensures backwards compatibility — existing `uses: elastic/ai-github-actions/claude-workflows/...@v0` references continue to work. |
There was a problem hiding this comment.
💬 NITPICK Symlink reference incorrect
The note says "existing
uses: elastic/ai-github-actions/claude-workflows/...@v0`` references continue to work" but this is misleading — the symlink ensures that oldworkflows/paths still work, not `claude-workflows/` paths. The text should say:"existing
uses: elastic/ai-github-actions/workflows/...@v0`` references continue to work"This correctly indicates that the symlink maintains backwards compatibility for the old path (
workflows/), not the new path.
|
Review submitted — approved with no requested changes.
Warning
|
1 participant
Addresses the documentation review feedback from #20. Changes are focused on making it easier for an Elastic employee to adopt these workflows without getting stuck.
Changes
High impact — would block adoption:
Secretssection documentingCOPILOT_GITHUB_TOKENand linking to gh-aw engine docs. Numbered the quick-start steps and added secret setup + verification steps.Medium impact — would cause confusion:
# Prevents git push even with Bash access. See SECURITY.md.on thecontents: readline.@claudevs/ai).uses:paths fromworkflows/toclaude-workflows/(across 20 files). The backwards-compat symlink still works, but docs now match the actual directory name.Low impact — minor improvements:
make setupinstalls (actionlint, action-validator, gh CLI, gh-aw compiler).27 files changed — all documentation, no functional changes. No workflow files in
.github/workflows/were modified.