Allow the arguments to Reusable Workflows (with) to be a (JSON) StringToken instead of supporting MappingToken only

[umarcor]

🏷️ Discussion Type

Bug

💬 Feature/Topic Area

Workflow Configuration

Discussion Details

When generating jobs programmatically, a JSON object/string can be declared in one job and then used to define a matrix in another job without explicitly unpacking all the keys and values.
The following is a (reusable) variation of https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/run-job-variations#using-an-output-to-define-two-matrices:

# common.yml

on:
  workflow_call:
    inputs:
      key:
        description: 'Name of the job in the configuration.'
        required: true
      submodules:
        description: 'Whether to checkout submodules (false, true or recursive).'
        required: true

jobs:

  matrix:
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.generate.outputs.matrix }}
    steps:
    - id: generate
      run: echo 'matrix=[10, 12, 14]' >> "$GITHUB_OUTPUT"
      
  jobs:
    needs: matrix
    runs-on: ubuntu-latest
    strategy:
      matrix:
        version: ${{ fromJson(needs.matrix.outputs.matrix) }}
    name: ${{ matrix.version }}
    steps:
    - run: echo 'Hello World!'

However, the same strategy fails when trying to pass arguments to the Reusable Workflow.
The following is a simplified case that tries to reuse the inputs of a workflow_dispatch (which are exactly the same as the inputs of the workflow_call of the reusable workflow common.yml).

# dispatch.yml

on:
  workflow_dispatch:
    inputs:
      key:
        description: 'Name of the job in the configuration.'
        required: true
      submodules:
        description: 'Whether to checkout submodules (false, true or recursive).'
        required: true

jobs:
  dispatch:
    uses: ./.github/workflows/common.yml
    with: ${{ fromJson(github.event.inputs) }}

The following error is produced:

Unrecognized named-value: 'github'. Located at position 10 within expression: fromJson(github.event.inputs), (Line: 45, Col: 11): Unexpected value '${{ fromJson(github.event.inputs) }}'

Similar results with inputs (with or without fromJson

Unrecognized named-value: 'inputs'. Located at position 10 within expression: fromJson(inputs), (Line: 45, Col: 11): Unexpected value '${{ fromJson(inputs) }}'

 Unrecognized named-value: 'inputs'. Located at position 1 within expression: inputs, (Line: 45, Col: 11): Unexpected value '${{ inputs }}'

When editing the workflow in GitHub, the tooltip suggests that parsing JSON strings is not supported:

Unrecognized named-value: 'inputs'
Unexpected value '${{ fromJson(inputs) }}'
Unexpected type 'StringToken' encountered while reading 'uses-with value'. The type 'MappingToken' was expected.

It would be really helpful if arguments to Reusable Workflows (and ideally to any step/action) could be parsed as strings. It would significantly reduce verbosity and maintenance.

This is a follow-up of https://github.com/orgs/community/discussions/9092

[github-actions[bot]]

💬 Your Product Feedback Has Been Submitted 🎉

Thank you for taking the time to share your insights with us! Your feedback is invaluable as we build a better GitHub experience for all our users.

Here's what you can expect moving forward ⏩

• Your input will be carefully reviewed and cataloged by members of our product teams. 
  • Due to the high volume of submissions, we may not always be able to provide individual responses.
  • Rest assured, your feedback will help chart our course for product improvements.
• Other users may engage with your post, sharing their own perspectives or experiences. 
• GitHub staff may reach out for further clarification or insight. 
  • We may 'Answer' your discussion if there is a current solution, workaround, or roadmap/changelog post related to the feedback.

Where to look to see what's shipping 👀

• Read the Changelog for real-time updates on the latest GitHub features, enhancements, and calls for feedback.
• Explore our Product Roadmap, which details upcoming major releases and initiatives.

What you can do in the meantime 💻

• Upvote and comment on other user feedback Discussions that resonate with you.
• Add more information at any point! Useful details include: use cases, relevant labels, desired outcomes, and any accompanying screenshots.

As a member of the GitHub community, your participation is essential. While we can't promise that every suggestion will be implemented, we want to emphasize that your feedback is instrumental in guiding our decisions and priorities.

Thank you once again for your contribution to making GitHub even better! We're grateful for your ongoing support and collaboration in shaping the future of our platform. ⭐

[vijay211983]

Authenticating with a GitHub App on behalf of a user

Your GitHub App can perform actions on behalf of a user, like creating an issue, posting a comment, or creating a deployment.

Your app can make API requests on behalf of a user. API requests made by an app on behalf of a user will be attributed to that user. For example, if your app posts a comment on behalf of a user, the GitHub UI will show the user's avatar photo along with the app's identicon badge as the author of the issue.

Similarly, if the request triggers a corresponding entry in the audit logs and security logs, the logs will list the user as the actor but will state that the "programmatic_access_type" is "GitHub App user-to-server token".

To make an API request on behalf of a user, the user must authorize your app. If an app is installed on an organization that includes multiple members, each member will need to authorize the app before the app can act on their behalf. An app does not need to be installed in order for a user to authorize the app.

When a user installs an app on an account, they grant the app permission to access the resources that it requested. During the installation process, they will also see a list of account permissions that the app can request for individual users. When a user authorizes an app, they grant the app permission to act on their behalf, and they grant the account permissions that the app requested.

Once a user has authorized your app, you can generate a user access token, which is a type of OAuth token. You should send the user access token in the Authorization header of your subsequent API requests. For more information about prompting a user to authorize your app and generating a user access token, see Generating a user access token for a GitHub App.

When operating on behalf of a user, your app's access is limited to ensure secure and appropriate access:

• The app can only access resources that the user has access to. If a user does not have access to a repository, your app cannot access that repository on their behalf even if the app is installed on that repository.
• The app can only access resources that it has permission to access. If your app does not have the Issues permission, it cannot create or read issues for the user, even if the user has access to the repository.
• The app can only access resources in an account where it is installed. If your app is only installed on a user's personal account, it cannot access resources in an organization that the user is a member of unless the app is also installed on that organization.

Requests made with a user access token are sometimes called "user-to-server" requests.

A token has the same capabilities to access resources and perform actions on those resources that the owner of the token has, and is further limited by any scopes or permissions granted to the token. A token cannot grant additional access capabilities to a user.

If you want to attribute app activity to the app instead of to a user, you should authenticate as an app installation instead. For more information, see Authenticating as a GitHub App installation.

Note

If a user reports that they cannot see resources owned by their organization after authorizing your GitHub App and the organization uses SAML SSO, instruct the user to start an active SAML session for their organization before reauthorizing. For more information, see SAML and GitHub Apps in the GitHub Enterprise Cloud documentation.

[tomm1990]

that tooltip is telling the truth. with: on a reusable workflow must be a yaml mapping (MappingToken). github won’t accept a string/json blob there, so this never works:

with: ${{ fromJson(github.event.inputs) }}

same for with: ${{ inputs }}. expressions are allowed on the values, not as a replacement for the whole mapping. that’s why you get Unexpected type 'StringToken'.

working pattern today - expand each input explicitly:

# dispatch.yml
on:
  workflow_dispatch:
    inputs:
      key:
        required: true
        type: string
      submodules:
        required: true
        type: string

jobs:
  dispatch:
    uses: ./.github/workflows/common.yml
    with:
      key: ${{ inputs.key }}
      submodules: ${{ inputs.submodules }}

for workflow_dispatch, prefer inputs.* over github.event.inputs.* (same values, cleaner).

if the set of keys is dynamic (you don’t know them at yaml-write time)

you still can’t splat into with:. options that actually compile:

1. pass one json string input and unpack inside the reusable workflow:

   # caller
   with:
     config_json: ${{ toJson(inputs) }}
   
   # callee workflow_call input
   # config_json: { type: string }
   # then fromJson(inputs.config_json).key inside jobs

2. or generate the caller yaml (same as you already do for matrices) so each key is written out as a mapping entry.

matrix fromJson(...) works cos that field expects a sequence/object expression. reusable with: is a different parser slot - intentional limitation, not a typo on your side.

so: +1 on the feature ask (StringToken → mapping would kill a ton of boilerplate). until then, explicit keys or a single json string input is the path that runs.

[umarcor]

pass one json string input and unpack inside the reusable workflow

I already do that in other use cases. However, that implies reimplementing which options/arguments are optional, which is their expected type and the optional default value. That functionality is already implemented in the interface of Reusable Workflows and Composite Actions. I would like to use that without reinventing the wheel.
Meanwhile, I use the explicit pattern despite the increased verbosity and maintenance.

[tomm1990]

that’s the real gap.

json-string → fromJson inside the callee skips the workflow_call contract (required / type / default). you end up re-validating what github already knows how to enforce on typed inputs. explicit with: mapping is the only path today that keeps that interface intact - verbose, but it doesn’t reinvent the schema.

there isn’t a middle ground right now: splat/StringToken with: still isn’t accepted, so you can’t both “pass the bag” and keep reusable-workflow input validation.

one thing that sometimes cuts the maintenance without dropping typed inputs: generate the caller with: block from the same source that defines the callee workflow_call.inputs (script / codegen), so optional/default/type live in one place and the mapping stays explicit for the parser.

curious on your setup so we’re not guessing:

1. roughly how many inputs on the reusable workflow, and how often does that set change?
2. are those input definitions hand-maintained yaml, or already generated somewhere?

if the schema is already generated, wiring the caller with: from that same generator is usually the least-pain holding pattern until github allows mapping-from-json. if it’s hand-written and changes a lot, the feature ask is basically the only clean fix - explicit mapping is just what you’re stuck with.