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 天内回复