jobs.<job_id>.runs-on format summary incomplete

[mpalmer]

Code of Conduct

• [X] 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/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on

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

This bullet point in the opening part of the runs-on documentation:

• You can provide runs-on as:

** a single string ** a single variable containing a string ** an array of strings, variables containing strings, or a combination of both

Fails to mention that you can also provide runs-on as a map containing either or both of the key(s) group and labels, as per the examples under the subheading "Choosing runners in a group". The result of this is that, unless you very carefully read the entire section, the existence of this alternate method of configuring the runs-on specification is left unknown.

Additional information

No response

[cmwilson21]

@mpalmer Thanks so much for opening an issue! I'll triage this for the team to take a look :eyes:

[Babo0o]

Code of Conduct

• [x] 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/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on

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

This bullet point in the opening part of the runs-on documentation:

• You can provide runs-on as:

** a single string ** a single variable containing a string ** an array of strings, variables containing strings, or a combination of both

Fails to mention that you can also provide runs-on as a map containing either or both of the key(s) group and labels, as per the examples under the subheading "Choosing runners in a group". The result of this is that, unless you very carefully read the entire section, the existence of this alternate method of configuring the runs-on specification is left unknown.

Additional information

No response

[Babo0o]

Goood

[SiaraMist]

Thanks so much for opening this issue, @mpalmer!

I can definitely see how it would be easy to miss the examples for using the group and label keys to assign the runs-on value.

To address this, I like your idea of adding another item to the list at the beginning of jobs.<job-id>.runs-on, that says something like:

You can provide runs-on as:

• a single string
• a single variable containing a string
• an array of strings, variables containing strings, or a combination of both
• a key: value pair using the group or label keys

You or anyone else is welcome to open a PR to update these docs! ⚡