Use matrix context in Jobs.job.if

[su-sisk]

Hi guys 🤠
I'm wondering if it's possible to use the matrix context in a jobs.job.if to control the execution ?
The docs states that we can use any context and expression to create conditionals.

You can use the jobs.<job_id>.if conditional to prevent a job from running unless a condition is met. You can use any supported context and expression to create a conditional.

quote

Sry if this is a stupid question, an example of my problem is shown below

Example

jobs:
  pre:
    runs-on: ubuntu-latest
    steps:
      - name: define matrix
        id: export-packages
        run: |
          echo "::set-output name=packages::[{ 'ms':'package-a', 'enabled': 'true' }, { 'ms':'package-b', 'enabled': 'false' }]"
    outputs:
      matrix: ${{ steps.export-packages.outputs.packages }}

  job-1:
    runs-on: ubuntu-latest
    needs:
      - pre
    strategy:
      matrix: 
        packages: ${{fromJSON(needs.pre.outputs.matrix)}}
    if: matrix.packages.enabled == 'true'
    steps:
      - name: "test"
        run: |
          echo "${{matrix.ms}} - ${{matrix.enabled}}"

Running this gives the following error:
The workflow is not valid. .github/workflows/matrix-example.yml (Line: 27, Col: 9): Unrecognized named-value: 'matrix'. Located at position 1 within expression: matrix.packages.enabled == 'true'

All i really wanna achive is to be able to "skip and mark job as skipped" So I could add a initial step to my job that checks this using bash script, but if that exits with 0 or 1 the job is marked as failed or success. Is it possible to mark the job as "skipped"? e.g through something like this? echo "::job-status='skipped' "

[antonblr]

@su-sisk - could you try it with the curly braces , like if: ${{ matrix.packages.enabled == 'true' }} ?

[skaugvoll]

Hi thanks for the reply. I tried with your suggestion still same error message.

Unrecognized named-value: 'matrix'. Located at position 1 within expression:

[antonblr]

Took a closer look: matrix context is not available at jobs.<job_id>.if level. You can use it at jobs.<job_id>.steps.if.
Something like:

steps:
  - name: "test"
    if: ${{ matrix.packages.enabled == 'true' }}
    run: echo "${{matrix.ms}} - ${{matrix.enabled}}"

Reference - https://docs.github.com/en/actions/learn-github-actions/contexts#determining-when-to-use-contexts

[fherreazcue]

Does anyone know why the matrix context is not available for jobs.<job_id>.if? The reference above shows that it is available almost anywhere except there... it is a bit annoying...

[DarrenBishop]

@fherreazcue the workaround (forgive me if this is obvious) is to pass your flag as an input in the called workflow and then it will be in an accessible context for the jobs (and there if condition) defined there.

@su-sisk, agree this is super annoying; you'd think after so many years (and plugins) after Jenkins, the semantic difference between aborted/skipped vs. failed vs. cancelled would be clear.

The reliance on exit-codes is unnecessarily unsophisticated i.e 0-zero for success and everything else is a fail; unless with the 0-zero magic number we add non-zero magic numbers to trigger/reflect the various job outcomes/conclusions...

But from a Bash step-run context, functions are an obvious way forward:

### Start Managed Internally Block (i.e. is enforced/always included [sourced])
> abort() {
    echo "Aborting run... this is not the same as failed!"
}

> readonly -f abort
### End Managed Internally Block

> abort
Aborting run... this is not the same as failed!

> abort() {
    echo "Let's monkey around... or otherwise inadvertently redefine abort() in some well-intentioned job step"
}
-bash: abort: readonly function

[brianjmurrell]

@fherreazcue the workaround (forgive me if this is obvious) is to pass your flag as an input in the called workflow and then it will be in an accessible context for the jobs (and there if condition) defined there.

It's not obvious to me. Could you provide an example of how the OP's workflow could be modified to implement your suggestion?

[DarrenBishop]

@brianjmurrell I'm sorry

Around the same time as my comment, I commented on another issue with an example; I'll replicate here:

The calling workflow (org/repo/.github/workflows/build_images.yaml [with and s]), triggered on push or pull_request:

name: Build Images

on:
  push:
    ...
  pull_request:
    ...

permissions:
  ...

jobs:
  determine-work:
     ...
  call-build-image:
    needs: determine-work
    strategy:
      matrix:
        image: [api, ui]
        include:
          - image: api
            enabled: ${{ needs.determine-work.outputs.build-api }}
          - image: ui
            enabled: ${{ needs.determine-work.outputs.build-ui }}
    uses: org/repo/.github/workflows/build_image.yaml@same-branch
    with:
      # build: ${{ matrix.enabled }} # <--- fails without fromJSON
      build: ${{ fromJSON(matrix.enabled) }}
      image: ${{ matrix.image }}
      tag: ${{ needs.determine-work.outputs.tag }}
    secrets: inherit
    permissions:
      id-token: write
      contents: read

The called workflow (org/repo/.github/workflows/build_image.yaml) i.e. triggered by workflow_call

name: Build Single Image

on:
  workflow_call:
    inputs:
      build:
        description: 'Flag whether to build the Image'
        required: true
        type: boolean
      image:
        description: 'Image to build: api or ui'
        required: true
        type: string
      tag:
        description: 'Image tag'
        required: true
        type: string

jobs:
  build-and-push:
    if: inputs.build
    ...

Go forth and conquer

[nrdxp]

Not sure if I should open another discussion to request a new feature where matrix can be extended to become available in an if. My main usecase is required jobs that are sometimes skipped if certain invariants haven't changed, which means it would suceed again if ran, and so we skip for efficiencies sake.

However, because of the information described here:
https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/collaborating-on-repositories-with-code-quality-features/troubleshooting-required-status-checks#handling-skipped-but-required-checks

This means that the job will not report it's status properly at all. If I could instead add a special boolean to the matrix json format I am using and simply check if: matrix.target.skipped == true that'd be all I need to satisfy the status checks.

Context

You can check out my draft PR for context here:
divnix/std-action#53

This system uses the Nix package manager as a base package builder for CI. Nix is a highly reproducible build system using formal methods to ensure that if inputs do not change, the build result should be the same. In CI, this means that if a given job is simply building a package, we can just skip it entirely if it has already been built in a previous round and its input hash has not changed. This presents a problem when status checks are required on certain builds however.

[e137300]

So, this is still an issue. I also have similar requirement where i need to access matrix properties under jobs.job.if but it throws the same error. no fix has been done yet its 2025!