-
Notifications
You must be signed in to change notification settings - Fork 59.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Replace misleading documentation about action inputs and outputs #33916
base: main
Are you sure you want to change the base?
Conversation
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 changesYou 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.
fpt: Free, Pro, Team |
This comment was marked as spam.
This comment was marked as spam.
@piotrekkr Thanks so much for opening a PR! I'll get this triaged for review ✨ |
Thanks for opening a pull request! We've triaged this issue for technical review by a subject matter expert 👀 |
This is a gentle bump for the docs team that this PR is waiting for technical review. |
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. |
@@ -36,18 +36,12 @@ Action metadata files use YAML syntax. If you're new to YAML, you can read "[Lea | |||
|
|||
## `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. | |||
**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 values are always converted to strings. We recommend using lowercase input ids. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Input values are always converted to strings.
I would leave this out. Environment variables are strings.
|
||
### Example: Specifying inputs | ||
|
||
This example configures two inputs: `num-octocats` and `octocat-eye-color`. The `num-octocats` input is not required and will default to a value of `1`. `octocat-eye-color` is required and has no default value. | ||
|
||
{% note %} | ||
|
||
**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 {% data variables.product.prodname_dotcom %}. For more information, see "[AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows)." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe just
**Note:** Actions using `required: true` will not automatically return an error if the input is not specified.
|
||
To access the environment variable in a Docker container action, you must pass the input using the `args` keyword in the action metadata file. For more information about the action metadata file for Docker container actions, see "[AUTOTITLE](/actions/creating-actions/creating-a-docker-container-action#creating-an-action-metadata-file)." | ||
|
||
For example, if a workflow defined the `num-octocats` and `octocat-eye-color` inputs, the action code could read the values of the inputs using the `INPUT_NUM-OCTOCATS` and `INPUT_OCTOCAT-EYE-COLOR` environment variables. | ||
|
||
### `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 `_`. | ||
**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, spaces, `-`, or `_`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Spaces should never have been allowed and aren't allowed for job IDs. I do not want to advertise/encourage this.
|
||
### `inputs.<input_id>.description` | ||
|
||
**Required** A `string` description of the input parameter. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Let's leave this Required
. We want to encourage descriptions, which will help with editing experiences.
|
||
### `inputs.<input_id>.required` | ||
|
||
**Optional** A `boolean` to indicate whether the action requires the input parameter. Set to `true` when the parameter is required. | ||
|
||
### `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. | ||
**Optional** A `string` representing the default value. The default value is used when an input parameter isn't specified in a workflow file. If input is not required and default value is not specified, {% data variables.product.prodname_dotcom %} will use empty string as a default value. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would suggest leaving the paragraph as is (simpler), unless there is a strong reason. Would prefer to keep the docs simpler.
@@ -107,11 +101,11 @@ outputs: | |||
|
|||
### `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 `_`. | |||
**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, space, `-`, or `_`. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
same as above (prefer not to advertise/encourage spaces)
|
||
### `outputs.<output_id>.description` | ||
|
||
**Required** A `string` description of the output parameter. | ||
**Optional** A `string` description of the output parameter. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
same as above
@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 ✨ |
Why:
Current docs for
inputs
andoutputs
in GitHub action metadata syntax contains some misleading statementsI've tested this
Input ids with uppercase letters are converted to lowercase during runtime.
usingand nothing is converted to lowercase
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.
Again, this paragraph seems to be mixing workflow inputs with action inputs.
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 whatyou can change these inputs manually
part actually means. Inputs are read-only afaik, right?As far as my tests got me,
space
characters are also valid to use in input ids.I tested this with composite and docker action:
and
And inputs in those action did not require any description and actions were run without problem
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.Tried and description can be omitted like below without any problems so it seems that it is optional.
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:
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).
data
directory.For content changes, I have completed the self-review checklist.