Workflow syntax reference doesn't document top-level `description` key
維護者通常 1 天內回覆
還沒有人認領這個 Issue。
評估
- 難度
- 2/5
- 預估耗時
- 1-3 小時
- 新手友好度
- 74/100
- Issue 類型
- 文件
- 描述清晰度
- 描述清楚
- 活躍度
- 活躍
- 技術堆疊
- github, yaml
研究方向
從連結文件頁面上的 workflow 語法參考開始，並將其中記載的頂層鍵與連結的 workflow schema 中的 description 項目進行比較。查看 repository 的文件貢獻指南，找到來源檔案和預覽流程。完成標準是：參考文件說明根層級的 description 是否受支援、其用途為何，以及它是否會顯示在 UI 中。
由索引模型根據 Issue 內容生成。
描述
Code of Conduct
- I have read and agree to the GitHub Docs project's Code of Conduct
What article on docs.github.com is affected?
https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
What part(s) of the article would you like to see updated?
The top-level keys documented are name, run-name, on, permissions, env, defaults, concurrency, cache-mode and jobs. There's no entry for description.
GitHub's own workflow schema has accepted a root-level description since January 2025:
- actions/languageservices@50b08a3 ("Add root-level description keyword") added it to
workflow-rootinworkflow-v1.0.json, with the description "A description for your workflow or reusable workflow", plus a test fixture. - The same key is in the runner's copy of the schema: actions/runner
src/Sdk/WorkflowParser/workflow-v1.0.json.
Could the reference add a description section saying whether it's supported, what it's for (e.g. describing reusable workflows), and whether it's shown anywhere in the UI?
Additional information
Because it isn't documented, third-party tools that follow the docs reject it. actionlint (v1.7.12, latest) reports unexpected key "description" for "workflow" section, and the SchemaStore github-workflow.json schema, used by many editors' YAML validation, doesn't allow it either. Meanwhile the official GitHub Actions VS Code extension accepts it. We ran into this reviewing a reusable workflow, where different tools gave opposite answers about whether the file was valid.
- 主要語言
- TypeScript
- 星號
- 21.3k
- 分支
- 69.4k
- 平均合併
- 12 小時 12 分鐘
- 30 天內合併 PR
- 84
環境準備
在瀏覽器裡用你自己的 GitHub 帳號啟動這個專案的開發容器。
- 提供 Dockerfile 或 Docker Compose 檔案
- 有 Pull Request 範本
- 閱讀貢獻指南
從這裡開始
- 先讀完整個 Issue，再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫，在一個分支上完成修改。
- 送出 Pull Request，並在描述裡引用這個 Issue 編號。
github/docs 的其他 Issue
-
content triage
難度 2/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆
-
Confusing content: evaluates the expression `hash "package-lock.json"` to derive the final key `npm-d5ea0750`可能已有人在做 @darshpatel1052 於 4 天前認領。 未關閉actions builder persona content
難度 1/5 1 小時以內 新手友好度 86/100
github/docs#46499 · 3 則留言 · 1 個 reaction ·
維護者通常 1 天內回覆
-
builder persona
難度 1/5 1-3 小時 新手友好度 88/100
維護者通常 1 天內回覆
-
builder persona content copilot
難度 1/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆
-
on.workflow_call.inputs.<input_id> description, required and default have no headings可能重新可做 關聯的 PR 已關閉且未合併。 未關閉actions builder persona
難度 2/5 1-3 小時 新手友好度 75/100
維護者通常 1 天內回覆
相似的 Issue
-
難度 2/5 1-3 小時 新手友好度 82/100
tensorflow/tfjs#8754 ·
-
tool-submission
難度 1/5 1 小時以內 新手友好度 83/100
BraveOPotato/NoSignups#2348 ·
-
難度 2/5 1-3 小時 新手友好度 78/100
code-yeongyu/oh-my-openagent#12784 ·
維護者通常 1 天內回覆
-
external-issue to-triage
難度 2/5 1-3 小時 新手友好度 71/100
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 72/100
MomsBloomOrg/momsbloom-resources#84 ·
維護者通常 1 天內回覆