Workflow syntax reference doesn't document top-level description key #46853

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-root in workflow-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.