Replace misleading documentation about action inputs and outputs

[piotrekkr]

Why:

Current docs for inputs and outputs in GitHub action metadata syntax contains some misleading statements

inputs

Optional Input parameters allow you to specify data that the action expects to use during runtime. {% data variables.product.prodname_dotcom %} stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommend using lowercase input ids.

I've tested this Input ids with uppercase letters are converted to lowercase during runtime. using

name: Demo Composite Action
description: Demo Composite Action

inputs:
  first-input ID:
    description: First input
    required: true
  second-INPUT_id:
    description: Second input
    required: false
    default: 1
  third_input_id:
    description: Third input
    required: false
runs:
  using: composite
  steps:
    - shell: bash
      run: env | grep ^INPUT_ || true
    - shell: bash
      run: echo '${{ toJSON(inputs) }}'

and nothing is converted to lowercase

Note: Workflows using required: true will not automatically return an error if the input is not specified for events that automatically trigger workflow runs. If you set required: true in your workflow file and are using workflow_dispatch to manually run the workflow, you will be required to specify inputs on GitHub. For more information, see "Events that trigger workflows."

Workflow files that use this action can use the with keyword to set an input value for octocat-eye-color. For more information about the with syntax, see "Workflow syntax for GitHub Actions."

This is misleading because documentation is about action metadata syntax and note is describing inputs in workflow metadata syntax. This has nothing to do with action inputs, I think.

When you specify an input in a workflow file or use a default input value, {% data variables.product.prodname_dotcom %} creates an environment variable for the input with the name INPUT_<VARIABLE_NAME>. The environment variable created converts input names to uppercase letters and replaces spaces with _ characters.

Again, this paragraph seems to be mixing workflow inputs with action inputs.

If the action is written using a composite, then it will not automatically get INPUT_<VARIABLE_NAME>. If the conversion doesn't occur, you can change these inputs manually.

Last sentence does not make much sense and I tested it. There is no INPUT_* variables present at all with composite actions. I don't even know what you can change these inputs manually part actually means. Inputs are read-only afaik, right?

inputs.<input_id>

Required A string identifier to associate with the input. The value of <input_id> is a map of the input's metadata. The <input_id> must be a unique identifier within the inputs object. The <input_id> must start with a letter or _ and contain only alphanumeric characters, -, or _.

As far as my tests got me, space characters are also valid to use in input ids.

inputs.<input_id>.description

Required A string description of the input parameter.

I tested this with composite and docker action:

name: Demo Docker Action
description: Demo Docker Action

inputs:
  first-input ID:
    required: true
  second-INPUT_id:
    required: false
    default: 1
  third_input_id:
    required: false

runs:
  using: 'docker'
  image: 'Dockerfile'
  args:
    - ${{ inputs['first-input ID'] }}
    - ${{ inputs.second-INPUT_id }}
    - ${{ inputs.third_input_id }}

and

name: Demo Composite Action
description: Demo Composite Action

inputs:
  first-input ID:
    required: true
  second-INPUT_id:
    required: false
    default: 1
  third_input_id:
    required: false
runs:
  using: composite
  steps:
    - shell: bash
      run: echo '${{ toJSON(inputs) }}'

And inputs in those action did not require any description and actions were run without problem

jobs:
  actions-examples:
    name: Actions Reuse
    runs-on: ubuntu-latest
    steps:
      - name: Use organization composite action
        uses: pkroczynski/action-demo-composite@inputs
        with:
          first-input ID: hello
      - name: Use organization docker action
        uses: pkroczynski/action-demo-docker@main
        with:
          first-input ID: hello

outputs.<output_id>

Required A string identifier to associate with the output. The value of <output_id> is a map of the output's metadata. The <output_id> must be a unique identifier within the outputs object. The <output_id> must start with a letter or _ and contain only alphanumeric characters, -, or _.

There seems to be also space allowed in output id. Tested with js action using core.setOutput('output 1', "test") and it was returned as action output.

outputs.<output_id>.description

Required A string description of the output parameter.

Tried and description can be omitted like below without any problems so it seems that it is optional.

outputs:
  output 1: {}

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

Updated docs a bit to reflect what is actually happening with inputs and outputs in actions.

Check off the following:

• [x] 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.

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

[github-actions[bot]]

Automatically generated comment ℹ️

This comment is automatically generated and will be overwritten every time changes are committed to this branch.

The table contains an overview of files in the content directory that have been changed in this pull request. It's provided to make it easy to review your changes on the staging site. Please note that changes to the data directory will not show up in this table.

---

Content directory changes

You may find it useful to copy this table into the pull request summary. There you can edit it to share links to important articles or changes and to give a high-level overview of how the changes in your pull request support the overall goals of the pull request.

Source	Preview	Production	What Changed
actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions.md	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10	fpt ghec ghes@ 3.14 3.13 3.12 3.11 3.10

---

fpt: Free, Pro, Team ghec: GitHub Enterprise Cloud ghes: GitHub Enterprise Server

[Lordthevopz]

dg

ในวันที่ พ. 10 ก.ค. 2024 14:13 Piotr @.***> เขียนว่า:

Why:

Current note and next paragraph for inputs in GitHub action metadata syntax contains this:

Note: Workflows using required: true will not automatically return an error if the input is not specified for events that automatically trigger workflow runs. If you set required: true in your workflow file and are using workflow_dispatch to manually run the workflow, you will be required to specify inputs on GitHub. For more information, see "Events that trigger workflows https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows ."

Workflow files that use this action can use the with keyword to set an input value for octocat-eye-color. For more information about the with syntax, see "Workflow syntax for GitHub Actions https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepswith ."

This is misleading because documentation is about action metadata syntax and note is describing inputs in workflow metadata syntax. This has nothing to do with action inputs, I think. What's being changed (if available, include any code snippets, screenshots, or gifs):

Changed note about inputs and added info about what is used in case of missing default values in not required input. 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 https://docs.github.com/en/contributing/collaborating-on-github-docs/self-review-checklist .

---

You can view, comment on, or merge this pull request online at:

https://github.com/github/docs/pull/33916 Commit Summary

• 9d8dab8 https://github.com/github/docs/pull/33916/commits/9d8dab8f9ed3db315cc4e5f4c60b5e4e19855dd5 Replace misleading note about action inputs

File Changes

(1 file https://github.com/github/docs/pull/33916/files)

• M content/actions/creating-actions/metadata-syntax-for-github-actions.md https://github.com/github/docs/pull/33916/files#diff-40c20329662b90a0f06aa88a004f251c8aed8a541325709b9e0058198c10cb4d (2)

Patch Links:

• https://github.com/github/docs/pull/33916.patch
• https://github.com/github/docs/pull/33916.diff

— Reply to this email directly, view it on GitHub https://github.com/github/docs/pull/33916, or unsubscribe https://github.com/notifications/unsubscribe-auth/BBUHVQVPBHW2KA4TRLX6O5LZLTNIVAVCNFSM6AAAAABKUIFGKWVHI2DSMVQWIX3LMV43ASLTON2WKOZSGM4TSOJSHAZTANA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

[nguyenalex836]

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

[github-actions[bot]]

Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert :eyes:

[github-actions[bot]]

This is a gentle bump for the docs team that this PR is waiting for technical review.

[github-actions[bot]]

A stale label has been added to this pull request because it has been open 7 days with no activity. To keep this PR open, add a comment or push a commit within 3 days.

[nguyenalex836]

@ericsciple Thank you very much for the review! 💛

@piotrekkr Once you've had a chance to update your PR per the suggestions @ericsciple made, we'll be happy to get this merged ✨

[github-actions[bot]]

This PR has been automatically closed because there has been no response to to our request for more information from the original author. Please reach out if you have the information we requested, or open a new issue to describing your changes. Then we can begin the review process.

[piotrekkr]

Hello again. I was on vacations for a week and was unable to respond to this and seems it was automatically closed. @nguyenalex836 Should I create new pr or this one can be reopened somehow? Thanks

[nguyenalex836]

@piotrekkr Apologies for the overzealous automation! I've just reopened this issue 💛

[piotrekkr]

@ericsciple Unless I've missed something, all is done. Let me know if anything else should be changed. I don't have good internet connection atm and cannot clone full repo to resolve conflicts. Will do this next week.

[github-actions[bot]]

A stale label has been added to this pull request because it has been open 7 days with no activity. To keep this PR open, add a comment or push a commit within 3 days.

[nguyenalex836]

@piotrekkr Thank you for addressing that feedback! I've approved the PR - once you are able to resolve those conflicts, we can get this merged 💛

[piotrekkr]

@nguyenalex836 I've rebased this PR on latest code from main.

[nguyenalex836]

@piotrekkr Thank you! Getting this merged now 💛

[github-actions[bot]]

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 :zap: