fromJSON should include an example of an array for runs-on

[jsoref]

Maintainer's note

We researched the question raised by this issue and provided clarification in this comment: #20495 (comment)

To open a PR against this issue, please add clarification of this syntax in the "jobs.<job_id>.runs-on" section of the "Workflow syntax for GitHub Actions" article.

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/learn-github-actions/expressions#fromjson
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?

Add an example-returning-a-runs-on-array similar to https://docs.github.com/en/actions/learn-github-actions/expressions#example-returning-a-json-object

Additional information

Normally in JSON, the basic types are:

• null
• booleans
• numbers
• strings
• arrays
• maps

In GitHub Workflows, strings are strange in that, maybe? they don't need to be wrapped in quotes, some of the time?

Except, in the example https://docs.github.com/en/actions/learn-github-actions/expressions#example-returning-a-json-object, keys and values are wrapped in quotes:

        run: echo "::set-output name=matrix::{\"include\":[{\"project\":\"foo\",\"config\":\"Debug\"},{\"project\":\"bar\",\"config\":\"Release\"}]}"

When I tried to add some magic for a dynamic runs-on that would sometimes be a string and sometimes be an array, I naively assumed that I'd need to wrap my array elements in quotes, but that didn't do the right thing.

See this PR:
commercialhaskell/stack#5856 (comment)

We can't seem to get this to work...

merge change https://github.com/commercialhaskell/stack/runs/8254107160?check_suite_focus=true

Requested labels: [self-hosted, linux, ARM64]
Job defined at: commercialhaskell/stack/.github/workflows/integration-tests.yml@refs/pull/5856/merge
Waiting for a runner to pick up this job...

merge change https://github.com/commercialhaskell/stack/runs/8254719771?check_suite_focus=true

Requested labels: "[self-hosted, linux, ARM64]"
Job defined at: commercialhaskell/stack/.github/workflows/integration-tests.yml@refs/pull/5856/merge
Waiting for a runner to pick up this job...

merge change https://github.com/commercialhaskell/stack/runs/8255017367?check_suite_focus=true

Requested labels: ["self-hosted", "linux", "ARM64"]
Job defined at: commercialhaskell/stack/.github/workflows/integration-tests.yml@refs/pull/5856/merge
Waiting for a runner to pick up this job...

merge change https://github.com/commercialhaskell/stack/runs/8255163889?check_suite_focus=true

Requested labels: [self-hosted, linux, ARM64]
Job defined at: commercialhaskell/stack/.github/workflows/integration-tests.yml@refs/pull/5856/merge
Waiting for a runner to pick up this job...

The last output appears to match the output for the working world
workflow https://github.com/commercialhaskell/stack/runs/8255316015?check_suite_focus=true

    runs-on: [self-hosted, linux, ARM64]

[jsoref]

The working example is apparently commercialhaskell/stack@ba70082
Updated based on the deprecation of ::set-output: commercialhaskell/stack@963ba33

https://github.com/commercialhaskell/stack/blob/1931538a4a3e5058d9432bff68b397c6804a96f2/.github/workflows/integration-tests.yml#L163

          echo "arm64=['self-hosted', 'linux', 'ARM64']" >> $GITHUB_OUTPUT

https://github.com/commercialhaskell/stack/blob/ba7008251f8bcec6ac0bd11f26031b760b7d68e6/.github/workflows/integration-tests.yml#L122

    runs-on: ${{ fromJSON(needs.configuration.outputs.arm64) }}

[cmwilson21]

👋 @jsoref Thanks for opening an issue. We appreciate all the details, too.

I'll get this triaged for review. ⚡

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[Mashudaamri]

Help me establish a link to github for an otp on the missing simcard

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[github-actions]

This is a gentle bump for the docs team that this issue is waiting for technical review.

[hubwriter]

I've had a look at this but am not familiar enough with this area to know whether, where, and how this should be documented, so I've asked for some SME assistance. Hopefully we can move this issue along soon.

[hubwriter]

The answer I've had on this is that the strings provided as the value of runs-on can be quoted but don't need to be where a simple word is used, like:

runs-on: [self-hosted, linux, x64, gpu]

Expressions must be quoted:

runs-on: [self-hosted, "${{ inputs.chosen-os }}"]

Perhaps to resolve this issue we could add some clarification of this to the syntax details for runs-on:
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on