Repository navigation
Documentation bug: expression numbers are mis-documented #43008
Description
Activity
@DarkaMaul has also observed that numbers in expressions don't fully adhere to the Number(...) coercion rules:
zizmorcore/zizmor#1628 (comment)
This means that it's pretty unclear where the semantics for numbers are actually coming from in GitHub Actions expressions. It'd be really great for the docs to offer more clarity here.
@woodruffw This looks fairly fundamental and important, so I will try to get an answer about it in a timely manner, but just be aware that the Actions team is dealing with a lot and aren't quick to get back to me about anything at the moment. Just for my own clarification, is the documentation accurate in saying "any number format supported by JSON" in the sense that it does support all number formats supported by JSON, it just also supports other number formats? Or is that claim inaccurate? Sometimes things work that aren't officially supported, and that's always a whole headache with the documentation.
Hi @Sharra-writes, thanks for the response!
Just for my own clarification, is the documentation accurate in saying "any number format supported by JSON" in the sense that it does support all number formats supported by JSON, it just also supports other number formats? Or is that claim inaccurate? Sometimes things work that aren't officially supported, and that's always a whole headache with the documentation.
It's accurate in the sense that it supports a superset of the number formats supported by JSON. In other words, all JSON numbers are parsed correctly, but a lot of other number formats (broadly, a subset of the ones accepted by JavaScript's Number(...)) are also supported.
@DarkaMaul triaged this and found the relevant code here, which does a lot more than JSON numbers:
A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.
This is definitely not stale.
A stale label has been added to this issue, because it has been open for 30 days with no activity. If you think this issue should remain open, please add a new comment.
This is definitely not stale.
@Sharra-writes is there any chance of getting these docs fixed? I think this is unfortunately still pretty misleading as-is.
@woodruffw I've removed the stale label and ensured it shouldn't be re-added. We'll do our best to get this in front of the right people as soon as possible, but unfortunately we can't guarantee a timeframe for responses and resolutions for issues generated via this repo. Thanks for your patience.
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
numberliteral 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:
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 aStringDatalexeme 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 zizmorcore/zizmor#1628 for a related downstream report.