explain that even though empty should be a good way to trigger the default, it doesn't

[jsoref]

trafficstars

Code of Conduct

• [X] 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/creating-actions/metadata-syntax-for-github-actions#inputsinput_iddefault

What part(s) of the article would you like to see updated?

inputs.<input_id>.default

Optional A string representing the default value. The default value is used when an input parameter isn't specified in a workflow file.

---

This documentation isn't technically wrong. It's just an incredibly unfortunate implementation behavior because if someone uses ${{ vars.something }} or ${{ secrets.something }} and something isn't defined in a repository (especially a fork -- this is a thing that happens in github then the workflow/action will not behave as a reasonable person would expect.

[!WARNING] An input that is evaluated to empty will be treated as present and suppress your default.

Anyone writing a workflow that relies on an input's default should take special care to consider cases where the values they're passing will not be present.

This especially includes ${{ vars.VARIABLE_NAME }} which are unlikely to be present when run in forks and ${{ secrets.SECRET_NAME }} which will generally not be present when run in a pull request from a fork.

Additional information

consider this workflow: https://github.com/check-spelling-sandbox/action-default-0/actions/runs/7821238024/workflow

https://github.com/check-spelling-sandbox/action-default-0/blame/8359a59cf30619d5cb0ecf3e2dbaeb475d8b30e6/.github/workflows/blank.yml#L12-L23

name: test

on:
  push:
  workflow_dispatch:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: test with default
        uses: ./

      - name: test with value
        uses: ./
        with:
          test: 10

      - name: test with possibly no value
        uses: ./
        with:
          test: "${{ vars.something }}"

https://github.com/check-spelling-sandbox/action-default-0/actions/runs/7821238024#summary-21337735816

test: [2]
test: [10]
test: []

[nguyenalex836]

@jsoref Thank you for opening this issue! I'll get this triaged for review ✨

[ChristopherHX]

Some hidden additional information about default values you might never saw before

(undocumented) easter egg (since second half of 2019, inherited from azure pipelines) of actions/runner allows to trigger the default on empty var

      - name: test with possibly no value
        uses: ./
        with:
          ${{ insert }}: |-
            ${{ vars.something
            && fromjson(format('{{"test": {0}}}', tojson(vars.something)))
            || fromjson('{}') }}

actually pretty ugly and act will fail when it would see it

Trivia the much better to read if, elseif and else syntax of Azure Pipelines are not available in GitHub Actions

This case would collapse to case 1 if vars.something is empty, otherwise would result in case 2.

[SiaraMist]

Hey @jsoref, thank you for opening this issue. 🙌

I do see how that behavior could be confusing when you run into it. If you would like to give product feedback, you can do that here: https://github.com/github/feedback/discussions

For docs updates, I don't think we should include this information in the Metadata syntax article. The intended audience for that article is people who write actions, and the intended audience of the edge case you are describing is people who are writing workflows and relying on default input values for the actions they are using.

We could add information about this to the jobs.<job_id>.steps[*].with section in the Workflow syntax article. I would probably explain that actions authors can denote default values that will be used when no value is assigned to an input parameter in a workflow that calls the action. Then maybe add a note that if you assign a value to an input parameter that evaluates to empty, it will not use the default value. You or anyone else is welcome to open a pull request to add this information!