Array input type support in reusable workflows

[HavenDV]

Is there any plan to support arrays for reusable workflow? I mean this - https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_callinputsinput_idtype

[ethomson]

Hi @HavenDV - we don't have any immediately plans here. Can you tell me a little more about how you envision using arrays? I'd love to understand your use case a little bit better.

[HavenDV]

Hi Edward. I have a universal workflow that I use in my projects - https://github.com/HavenDV/workflows/blob/main/.github/workflows/dotnet_build-test-publish.yml. There are input variables like this:

windows-sdk-version:
  required: false
  type: string
  default: ''
  
windows-sdk-version2:
  required: false
  type: string
  default: ''
  
windows-sdk-version3:
  required: false
  type: string
  default: ''
  
windows-sdk-version4:
  required: false
  type: string
  default: ''

which are used like this:

- name: Setup Windows SDK
  if: inputs.windows-sdk-version != '' &&
      inputs.windows-sdk-version != '16299'
  uses: GuillaumeFalourd/setup-windows10-sdk-action@v1
  with:
    sdk-version: ${{ inputs.windows-sdk-version }}

- name: Setup Windows SDK
  if: inputs.windows-sdk-version2 != '' &&
      inputs.windows-sdk-version2 != '16299'
  uses: GuillaumeFalourd/setup-windows10-sdk-action@v1
  with:
    sdk-version: ${{ inputs.windows-sdk-version2 }}

- name: Setup Windows SDK
  if: inputs.windows-sdk-version3 != '' &&
      inputs.windows-sdk-version3 != '16299'
  uses: GuillaumeFalourd/setup-windows10-sdk-action@v1
  with:
    sdk-version: ${{ inputs.windows-sdk-version3 }}

- name: Setup Windows SDK
  if: inputs.windows-sdk-version4 != '' &&
      inputs.windows-sdk-version4 != '16299'
  uses: GuillaumeFalourd/setup-windows10-sdk-action@v1
  with:
    sdk-version: ${{ inputs.windows-sdk-version4 }}
  
- name: Install Windows SDK 10.0.16299
  if: inputs.windows-sdk-version == '16299' ||
      inputs.windows-sdk-version2 == '16299' ||
      inputs.windows-sdk-version3 == '16299' ||
      inputs.windows-sdk-version4 == '16299'
  shell: pwsh
  run: |
    Invoke-WebRequest -Uri https://go.microsoft.com/fwlink/p/?linkid=864422 -OutFile winsdk.exe
    $startInfo = New-Object System.Diagnostics.ProcessStartInfo
    $startInfo.FileName = "winsdk.exe"
    $startInfo.Arguments = "/norestart /quiet"
    $process = New-Object System.Diagnostics.Process
    $process.StartInfo = $startInfo
    $process.Start()
    $process.WaitForExit() 

I'm not very familiar with the YAML specification, so I could suggest an implementation like this:
Input variable:

windows-sdk-versions:
  required: false
  type: string
  is-array: true

External usage:

with:
  windows-sdk-versions: 
    - 16299
    - 18600

Internal usage:

- name: Setup Windows SDK
  if: inputs.windows-sdk-versions[*] != '16299' # for each windows-sdk-version != '16299' it will be expanded into the original code
  uses: GuillaumeFalourd/setup-windows10-sdk-action@v1
  with:
    sdk-version: ${{ inputs.windows-sdk-versions[*] }}

- name: Install Windows SDK 10.0.16299
  if: inputs.windows-sdk-versions[*] == '16299' # if any of windows-sdk-versions is '16299'
  shell: pwsh
  run: |
    Invoke-WebRequest -Uri https://go.microsoft.com/fwlink/p/?linkid=864422 -OutFile winsdk.exe
    $startInfo = New-Object System.Diagnostics.ProcessStartInfo
    $startInfo.FileName = "winsdk.exe"
    $startInfo.Arguments = "/norestart /quiet"
    $process = New-Object System.Diagnostics.Process
    $process.StartInfo = $startInfo

I guess this should also support passing an array without expanding for those actions that support arrays

The same logic is fully applicable to the asset- input variables from this workflow and greatly simplifies the code.

P.S. Another version of the syntax besides [*]: .* . This is more in line with the style that is applied in Github Actions. But this is a little confusing, because the [] operator is more familiar to programmers and denotes array expansion.

[Firehed]

@ethomson I'll add another use-case for you, as I'm also struggling to find an ergonomic (and secure) solution here:

I want to add an array (well, dictionary) input to one of my actions because the value(s) are intended to be passed to repeated CLI arg. In my specific case, I want to be able to pass multiple --build-arg flags to a docker build command.

Today, I'd have to structure the Action's inputs where the user would provide some sort of delimited string, which I'd then have to parse before use. This is error-prone and requires escaping or limits the valid inputs to the action, neither of which are great. Instead, it would be far more intuitive (both as an actions user and developer) to be able to use something like:

- uses: my/action
  with:
    simple_input: stringval
    dict_input:
      foo: foo_val
      bar: bar_val

In my case, a list would also work fine, although may be a bit clumsier:

- uses: my/action
  with:
    simple_input: stringval
    list_input:
      - foo=foo_val
      - bar=bar_val

Both of these are going to be more reliable and easier to work with than splitting strings based on commas, spaces, etc (which my action already needs to do for a different input). It also very clearly communicates to the user what they need to provide; there's less need to go back and forth on documentation which may drift from the actual code and action.yml

Anyway, food for thought. Hope this use case is something you find meaningful!

[pronovic]

Another use case is matrix builds. I have a workflow that implements my build process, general enough to be shared between multiple different Python projects. However, those different projects sometimes support different versions of Python and hence need a different set versions in their matrix:

    strategy:
      matrix:
        python: [ "3.9", "3.10" ]  

I would prefer to set the list of matrix versions as an input in my shared pipeline:

    strategy:
      matrix:
        python: "${{ inputs.PYTHON_VERSIONS }}"

However, since strategy.matrix.python needs an array value, I don't see an obvious way to accomplish that.

[sigprof]

Actually you can do things like

strategy:
  matrix: ${{ fromJSON(inputs.python_matrix) }}

I did not try using fromJSON in subkeys of matrix: — maybe that does not work; but specifying the whole matrix: value that way definitely works and even is documented.

You may add a separate setup job that prepares the matrix definitions in the required format using jq -c in a shell script, or maybe actions/github-script, and then have something like this in your real jobs:

needs:
  - setup
strategy:
  matrix: ${{ fromJSON(needs.setup.outputs.python_matrix) }}

What is missing is some support for passing YAML structured data to actions or workflows — the only place that accepts arbitrarily nested YAML data structures is matrix:, and in all other places you need to provide a string, so you would need to quote the JSON or YAML data as a string, possibly losing help from the editor as the result.

[ksenia-loseva]

This works, thank you! Didn't end up needing to add setup part or some script, simple ${{ fromJSON(inputs.python_matrix) }} as a parameter was enough

[digitalcrab]

Another good usecase is self hosted runners + reusable workflows. I want to pass the "run-on" to the reusable workflow and in case of self-hosted I have to pass at least 2 items. Not having a list type makes this task a bit tricky.

[moyolawal]

Anyone have a workaround for this? Seems only a singular label (string) is supported. Multiple labels do not work

[mathio]

I am struggling with the same thing. Since reusable workflows do not support runs-on in the action that calls it, I would like to pass it as input. However it only works for Github-hosted runners like ubuntu-latest.

@digitalcrab were you able to solve this with any workarounds?

[Artsu]

For anyone coming here via google, the solution from Teakowa works for runs-on as well: https://github.com/orgs/community/discussions/11692#discussioncomment-3541856

with:
  runs_on: "['custom', 'linux', 'foo']"

inputs:
  runs_on:
    required: true
    type: string
     
....
      
runs-on: ${{ fromJson(inputs.runs_on) }}

[patrickhilgenstock]

another use case we found while configuring cypress was the matrix parameter for on how many instances this is supposed to run
https://github.com/cypress-io/github-action#parallel

name: Cypress run
    runs-on: ubuntu-20.04
    strategy:
      # when one test fails, DO NOT cancel the other
      # containers, because this will kill Cypress processes
      # leaving the Dashboard hanging ...
      # https://github.com/cypress-io/github-action/issues/48
      fail-fast: false
      matrix:
        # run 3 copies of the current job in parallel
        containers: [1, 2, 3]

[umermughal]

In my case, I need comma-separated values dynamically from the Manual triggering workflow. So here is my solution

name: Manual workflow
on:
  workflow_dispatch:
    inputs:
      projects:
        required: true
        type: string # like project1,project2,project3
jobs:
  setup:
    runs-on: ubuntu-latest
    outputs:
      projects: ${{ steps.vars.outputs.project_list }}
    steps:
      - name: Create an array of projects
        id: vars
        run: echo "::set-output name=project_list::$(jq 'split(",")' -Rc <(echo '${{ inputs.projects }}'))"
  build:
    needs: setup
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [16.x]
        project: ${{ fromJson(needs.setup.outputs.projects) }}
    steps:
    - name: build project ${{ matrix.project }}
      run: echo "project=${{ matrix.project }}" 

[Teakowa]

I have an dumb but solvable solution case

You can input arrays that use double and single quotes:

workflow_call:
  inputs:
    runs-on:
      default: "['ubuntu-latest']"
      required: false
      type: string

then use fromJson in matrix

strategy:
  matrix:
    os: ${{ fromJson(inputs.runs-on) }}

runs-on: ${{ matrix.os }}

https://github.com/XNXKTech/workflows/blob/main/.github/workflows/codeql.yml

That'll work, but this should be a problem that GitHub needs to solve.🤨

[Teakowa]

I think default, required, and type need to be tabbed over one.

Yes I edit it a bit thanks

[ShahroZafar]

For the usecase where we only need to parameterize runs-on, I believe this works in the mentioned case

inputs:
  runner_labels:
  type: string
  default: "['self-hosted', 'Linux']"

runs-on: ${{ fromJson(inputs.runner_labels) }}

[wt-asw]

Thank you for this. I am also trying to pass a list to a reusable workflow.

[t-readyroc]

Thanks so much for this! Just a note, actionlint will fail the param if the param is expecting a sequence/list, e.g. (using this workaround for passing a list of container volume mounts to a shared workflow):

maven-tests-action.yml:64:16: "volumes" section must be sequence node but got scalar node with "!!str" tag [syntax-check]
   |
64 |       volumes: ${{ fromJson(inputs.VOL_MNTS) }}

But even though I got the above error, the workflow worked!

[weaponsforge]

This worked for me! ❤️ Thanks lots for the tips. I've been trying to pass an array of strings input parameter to a reusable workflow, guessing & testing which format will push through. This by far is the simplest and most straightforward method.

[marcinkubica]

Hi @ethomson
Passing an array to the reusable workflow matrix is my use case.
For that, thanks @Teakowa for your tip!

[scottw-kr]

I was looking for this in the docs. Guess it's still not an option, so I'm either going to have to run the called workflow n times from the caller workflow or use this fromJson approach.

[adsanz-atalanta]

My usecase is a bit different I have a custom action which will delete the current folder after the jobs runs, this is because we are using a persistent instance as a runner. I would love to be able to add an input that will be an array of directories, that array will be defined by the workflow where I'm calling this action from and used inside the action to delete the desired folders.

[joshua-temple]

Today, I have an Atlas Operator re-useable workflow that takes in a handful of inputs.

It updates the appropriate manifests via Kustomize based on said inputs, but given the general nature of workflows, we can only make one deployment update per workflow run.

What would be ideal is if I could define this object that took all of these inputs, and instruct the workflow to expect an array of this object, so that I can iterate over it via synchronous matrix execution and in turn run this workflow once for all deploys, rather than once per deploy.

I realize this is where I may be in the wrong place.. so please redirect me if so

Now, I realize I can (and am actively working on such) pass an array of said object that contains all of these inputs as a json string and extrapolate from there, but where there is a use case, there is at least cause to share it.

[kmezynski]

@ethomson It has been a year and a half since the ticket was created, and the community has provided incredibly valuable feedback. We're eager to know if there have been any developments in this regard, or if there are any plans to extend support for list-type (perhaps even dictionary-type) inputs.

[davorg]

Hi. Any update on this? This discussion has plenty of good use cases, and the workarounds are all pretty clunky. Would be great to get this feature properly supported.

[voolaidk]

+1 for array as an input. My use case is also passing multiple args to docker build as mentioned above. There are workarounds but they are errorprone and hacky.

[mitchelbaker-cisa]

Any update on getting this feature supported? I implemented an "array type" via the workarounds shared here, but it's not perfect by any means.

Using a combination of the existing string type and the ${{ fromJSON() }} syntax when passed into a matrix strategy. Current workflow implementation for reference if anyone is interested.

workflow_dispatch:
    inputs:
      operating-system:
        description: "Choose operating system(s), format must be an array of strings:"
        required: true
        type: string
        default: "['windows-latest', 'macos-latest']"

jobs:
  configuration:
    # this workflow can be triggered via workflow_dispatch and push/pull_request events, do some processing here

  smoke-test:
    needs: configuration
    strategy:
      fail-fast: false
      matrix:
        operating-system: ${{ fromJSON(needs.configuration.outputs.operating-system) }}
    runs-on: ${{ matrix.operating-system }}
    steps:
      ...

[sorced-jim]

The join function already exists. Adding a split method would (a) make the api more consistent, and (b) solve most of the problems listed here.

[ArjunDandagi]

+1 for arrays as input parameters . we are building reusable workflows for our platform users and without this feature we are losing the readability and usability of the re-usable workflow. the goal is to pass n strings as input to a task inside a job that prepares an artifact and upload to github artefacts.