feat: describe matrix variables of type array of objects

[deemp]

Why:

Partially closes: #26469

I used this hidden knowledge in freckle/stack-action#35 and decided to document it.

What's being changed (if available, include any code snippets, screenshots, or gifs):

Check off the following:

• I have reviewed my changes in staging, available via the View deployment link in this PR's timeline (this link will be available after opening the PR).

  • For content changes, you will also see an automatically generated comment with links directly to pages you've modified. The comment won't appear if your PR only edits files in the data directory.

• For content changes, I have completed the self-review checklist.

[welcome]

Thanks for opening this pull request! A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[nguyenalex836]

@deemp Thanks so much for opening a PR! I'll get this triaged for review ✨

[ferdnyc]

This isn't technically correct — matrix.node.env is simply not set for contexts where it's not included as part of the matrix. It's not part of the matrix.node object at all. All contexts are not created with the same structure, when matrix expansion is performed on homogeneous objects. Instead, each expanded context has whatever structure is explicitly defined by its set of inputs.

GitHub's workflow syntax expands ${{ foo }} to the empty string, for any undefined foo, but that doesn't mean that object actually exists.

[ferdnyc]

Which is something that actually requires some care, because for example this workflow:

jobs:
  build:
    runs-on: ${{ matrix.os.host }}
    strategy:
      matrix:
        os:
          - host: macos-latest
          - host: windows-latest
            shell: 'msys2 {0}'
          - host: ubuntu-latest
        compiler:
          - gcc
          - clang
    defaults:
      run:
        shell: ${{ matrix.os.shell }}

...will fail on Ubuntu and macOS, when it tries to set the run.shell default value to nothing.

Error: The template is not valid. foo.yml (Line: Y, Col: X): Unexpected value ''

[ferdnyc]

It can be fixed with a fallback, e.g.:

defaults:
  run:
    shell: ${{ matrix.os.shell || 'bash' }}

[deemp]

GitHub's workflow syntax expands ${{ foo }} to the empty string, for any undefined foo, but that doesn't mean that object actually exists.

Where is this documented?

[deemp]

Ah, I see (link)

If you attempt to dereference a nonexistent property, it will evaluate to an empty string.

[jc-clark]

Thank you for making this update @deemp!

I added a couple suggestions below and would love to hear what you think.

There are some versions of GitHub Enterprise Server that do not support Node 20. To adjust for this, we use feature-based versioning. The actions-node20-support feature-based versioning file to make sure that only the right versions of our documentation show information about Node 20.

My question for you is would Node 16 be a suitable replacement in this case?

Thanks!

[nguyenalex836]

Hi @deemp 👋 ! Please let us know your thoughts regarding @jc-clark's last response 💛

[deemp]

@jc-clark, @nguyenalex836, thanks for a review. I believe these node versions are OK.

The point of this example was to demonstrate how a matrix unwraps into multiple job configurations. If you think an example without specific node versions is more maintainable, feel free to use something instead of node.

[github-actions]

Thanks very much for contributing! Your pull request has been merged 🎉 You should see your changes appear on the site in approximately 24 hours. If you're looking for your next contribution, check out our help wanted issues ⚡