Documentation bug: expression numbers are mis-documented

Open Beginner friendly
#43,008 11 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
github-actions, javascript
Domain
documentation

Research direction

Start with the “Literals” section of the GitHub Actions expression syntax page and compare the Free, Pro, and Teams, GHES, and GHEC versions. Review the referenced parser source at expressions/src/data/string.ts lines 14–16 and the linked Number coercion rules. Done means the documentation accurately describes accepted number literals across all affected pages.

Written by the indexing model from the issue text.

Description

builder persona content github_actions never-stale
Code of Conduct
What article on docs.github.com is affected?

The "Literals" section of the GitHub Actions expression syntax page:

https://docs.github.com/en/actions/reference/workflows-and-actions/expressions#literals

That link is for the "Free, Pro, and Teams" page, but the GHES and GHEC pages are also affected.

What part(s) of the article would you like to see updated?

The number literal is documented as "Any number format supported by JSON." However, in reality, the GitHub Actions expression parser takes a much larger set of literals, which it coerces to numbers.

For example, neither hex nor octal literals are valid in JSON, but GitHub Actions accepts them. For example:

${{ 0xff }}
${{ 0o777 }}

More generally, GitHub Actions appears to support any number literal that the JavaScript Number(...) constructor can coerce a string from. Those coercion rules are documented here:

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number#number_coercion

This can be seen in the official GitHub Actions expression parser, which appears to use the Number(...) constructor when turning a StringData lexeme into a number:

https://github.com/actions/languageservices/blob/fb5c6e4f27bb1ddf512609a6a341aadd17ce86f3/expressions/src/data/string.ts#L14-L16

Additional information

Yes, this is trivially reproducible in any GitHub Actions workflow or action definition.

See https://github.com/zizmorcore/zizmor/pull/1628 for a related downstream report.

Dominant language
TypeScript
Stars
20.9k
Forks
68.8k
Avg merge
15h 4m
Merged PRs (30d)
103

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from github/docs

All issues in github/docs

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.