Note
You can build Docker container, JavaScript, and composite actions. Actions require a metadata file to define the inputs, outputs, and runs configuration for your action. Action metadata files use YAML syntax, and the metadata filename must be either action.yml or action.yaml. The preferred format is action.yml.
name
Required The name of your action. GitHub displays the name in the Actions tab to help visually identify actions in each job.
author
Optional The name of the action's author.
description
Required A short description of the action.
inputs
Optional Input parameters allow you to specify data that the action expects to use during runtime. GitHub stores input parameters as environment variables. We recommend using lowercase input ids.
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
Actions using required: true will not automatically return an error if the input is not specified.
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.
inputs:
num-octocats:
description: 'Number of Octocats'
required: false
default: '1'
octocat-eye-color:
description: 'Eye color of the Octocats'
required: true
When you specify an input, GitHub 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.
If the action is written using a composite, then it will not automatically get INPUT_<VARIABLE_NAME>. With composite actions you can use the inputs context to access action inputs.
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 Creating a Docker container action.
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 _.
inputs.<input_id>.description
Required A string description of the input parameter.
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.
inputs.<input_id>.deprecationMessage
Optional If the input parameter is used, this string is logged as a warning message. You can use this warning to notify users that the input is closing down and mention any alternatives.
outputs for Docker container and JavaScript actions
Optional Output parameters allow you to declare data that an action sets. Actions that run later in a workflow can use the output data set in previously run actions. For example, if you had an action that performed the addition of two inputs (x + y = z), the action could output the sum (z) for other actions to use as an input.
Outputs can be a maximum of 1 MB per job. The total of all outputs in a workflow run can be a maximum of 50 MB. Size is approximated based on UTF-16 encoding.
If you don't declare an output in your action metadata file, you can still set outputs and use them in a workflow. For more information on setting outputs in an action, see Workflow commands for GitHub Actions.
Example: Declaring outputs for Docker container and JavaScript actions
outputs:
sum: # id of the output
description: 'The sum of the inputs'
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 _.