Metadata syntax for GitHub Actions

About YAML syntax for GitHub Actions

All actions require a metadata file. The metadata filename must be eitheraction.ymloraction.yaml.The data in the metadata file defines the inputs, outputs, and runs configuration for your action.

Action metadata files use YAML syntax. If you're new to YAML, you can read "Learn YAML in five minutes."

`name`

RequiredThe name of your action. GitHub displays thenamein theActionstab to help visually identify actions in each job.

`author`

OptionalThe name of the action's author.

`description`

RequiredA short description of the action.

OptionalInput parameters allow you to specify data that the action expects to use during runtime. GitHub stores input parameters as environment variables. Input ids with uppercase letters are converted to lowercase during runtime. We recommend using lowercase input ids.

Example: Specifying inputs

This example configures two inputs:num-octocatsandoctocat-eye-color.Thenum-octocatsinput is not required and will default to a value of1.octocat-eye-coloris required and has no default value.

Note:Workflows usingrequired: truewill not automatically return an error if the input is not specified for events that automatically trigger workflow runs. If you setrequired: truein your workflow file and are usingworkflow_dispatchto 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 thewithkeyword to set an input value foroctocat-eye-color.For more information about thewithsyntax, 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 in a workflow file or use a default input value, GitHub creates an environment variable for the input with the nameINPUT_<VARIABLE_NAME>.The environment variable created converts input names to uppercase letters and replaces spaces with_characters.

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

To access the environment variable in a Docker container action, you must pass the input using theargskeyword 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 thenum-octocatsandoctocat-eye-colorinputs, the action code could read the values of the inputs using theINPUT_NUM-OCTOCATSandINPUT_OCTOCAT-EYE-COLORenvironment variables.

`inputs.<input_id>`

RequiredAstringidentifier 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 theinputsobject. The<input_id>must start with a letter or_and contain only Alpha numeric characters,-,or_.

`inputs.<input_id>.description`

RequiredAstringdescription of the input parameter.

`inputs.<input_id>.required`

OptionalAbooleanto indicate whether the action requires the input parameter. Set totruewhen the parameter is required.

`inputs.<input_id>.default`

OptionalAstringrepresenting the default value. The default value is used when an input parameter isn't specified in a workflow file.

`inputs.<input_id>.deprecationMessage`

OptionalIf the input parameter is used, thisstringis logged as a warning message. You can use this warning to notify users that the input is deprecated and mention any alternatives.

`outputs`for Docker container and JavaScript actions

OptionalOutput 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 are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.

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>`

RequiredAstringidentifier 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 theoutputsobject. The<output_id>must start with a letter or_and contain only Alpha numeric characters,-,or_.

`outputs.<output_id>.description`

RequiredAstringdescription of the output parameter.

`outputs`for composite actions

Optionaloutputsuse the same parameters asoutputs.<output_id>andoutputs.<output_id>.description(see "outputsfor Docker container and JavaScript actions"), but also includes thevaluetoken.

Outputs are Unicode strings, and can be a maximum of 1 MB. The total of all outputs in a workflow run can be a maximum of 50 MB.

Example: Declaring outputs for composite actions

outputs:
random-number:
description:"Random number"
value:${{steps.random-number-generator.outputs.random-id}}
runs:
using:"composite"
steps:
-id:random-number-generator
run:echo"random-id=$(echo $RANDOM)">>$GITHUB_OUTPUT
shell:bash

`outputs.<output_id>.value`

RequiredThe value that the output parameter will be mapped to. You can set this to astringor an expression with context. For example, you can use thestepscontext to set thevalueof an output to the output value of a step.

For more information on how to use context syntax, see "Accessing contextual information about workflow runs."

`runs`

RequiredSpecifies whether this is a JavaScript action, a composite action, or a Docker container action and how the action is executed.

`runs`for JavaScript actions

RequiredConfigures the path to the action's code and the runtime used to execute the code.

Example: Using Node.js v20

runs:
using:'node20'
main:'main.js'

`runs.using`for JavaScript actions

RequiredThe runtime used to execute the code specified inmain.

Usenode20for Node.js v20.

`runs.main`

RequiredThe file that contains your action code. The runtime specified inusingexecutes this file.

`runs.pre`

OptionalAllows you to run a script at the start of a job, before themain:action begins. For example, you can usepre:to run a prerequisite setup script. The runtime specified with theusingsyntax will execute this file. Thepre:action always runs by default but you can override this usingruns.pre-if.

In this example, thepre:action runs a script calledsetup.js:

runs:
using:'node20'
pre:'setup.js'
main:'index.js'
post:'cleanup.js'

`runs.pre-if`

OptionalAllows you to define conditions for thepre:action execution. Thepre:action will only run if the conditions inpre-ifare met. If not set, thenpre-ifdefaults toalways().Inpre-if,status check functions evaluate against the job's status, not the action's own status.

Note that thestepcontext is unavailable, as no steps have run yet.

In this example,cleanup.jsonly runs on Linux-based runners:

pre:'cleanup.js'
pre-if:runner.os=='linux'

`runs.post`

OptionalAllows you to run a script at the end of a job, once themain:action has completed. For example, you can usepost:to terminate certain processes or remove unneeded files. The runtime specified with theusingsyntax will execute this file.

In this example, thepost:action runs a script calledcleanup.js:

runs:
using:'node20'
main:'index.js'
post:'cleanup.js'

Thepost:action always runs by default but you can override this usingpost-if.

`runs.post-if`

OptionalAllows you to define conditions for thepost:action execution. Thepost:action will only run if the conditions inpost-ifare met. If not set, thenpost-ifdefaults toalways().Inpost-if,status check functions evaluate against the job's status, not the action's own status.

For example, thiscleanup.jswill only run on Linux-based runners:

post:'cleanup.js'
post-if:runner.os=='linux'

`runs`for composite actions

RequiredConfigures the path to the composite action.

`runs.using`for composite actions

RequiredYou must set this value to'composite'.

`runs.steps`

RequiredThe steps that you plan to run in this action. These can be eitherrunsteps orusessteps.

`runs.steps[*].run`

OptionalThe command you want to run. This can be inline or a script in your action repository:

runs:
using:"composite"
steps:
-run:${{github.action_path}}/test/script.sh
shell:bash

Alternatively, you can use$GITHUB_ACTION_PATH:

runs:
using:"composite"
steps:
-run:$GITHUB_ACTION_PATH/script.sh
shell:bash

For more information, see "Accessing contextual information about workflow runs".

`runs.steps[*].shell`

OptionalThe shell where you want to run the command. You can use any of the shells listed in "Workflow syntax for GitHub Actions."Required ifrunis set.

`runs.steps[*].if`

OptionalYou can use theifconditional to prevent a step from running unless a condition is met. You can use any supported context and expression to create a conditional.

When you use expressions in anifconditional, you can, optionally, omit the${{ }}expression syntax because GitHub Actions automatically evaluates theifconditional as an expression. However, this exception does not apply everywhere.

You must always use the${{ }}expression syntax or escape with'',"",or()when the expression starts with!,since!is reserved notation in YAML format. For example:

if:${{!startsWith(github.ref,'refs/tags/')}}

For more information, see "Evaluate expressions in workflows and actions."

Example: Using contexts

This step only runs when the event type is apull_requestand the event action isunassigned.

steps:
-run:echoThiseventisapullrequestthathadanassigneeremoved.
if:${{github.event_name=='pull_request'&&github.event.action=='unassigned'}}

Example: Using status check functions

Themy backup steponly runs when the previous step of a composite action fails. For more information, see "Evaluate expressions in workflows and actions."

steps:
-name:Myfirststep
uses:octo-org/action-name@main
-name:Mybackupstep
if:${{failure()}}
uses:actions/[email protected]

`runs.steps[*].name`

OptionalThe name of the composite step.

`runs.steps[*].id`

OptionalA unique identifier for the step. You can use theidto reference the step in contexts. For more information, see "Accessing contextual information about workflow runs."

`runs.steps[*].env`

OptionalSets amapof environment variables for only that step. If you want to modify the environment variable stored in the workflow, useecho "{name}={value}" >> $GITHUB_ENVin a composite step.

`runs.steps[*].working-directory`

OptionalSpecifies the working directory where the command is run.

`runs.steps[*].uses`

OptionalSelects an action to run as part of a step in your job. An action is a reusable unit of code. You can use an action defined in the same repository as the workflow, a public repository, or in apublished Docker container image.

We strongly recommend that you include the version of the action you are using by specifying a Git ref, SHA, or Docker tag number. If you don't specify a version, it could break your workflows or cause unexpected behavior when the action owner publishes an update.

Using the commit SHA of a released action version is the safest for stability and security.
Using the specific major action version allows you to receive critical fixes and security patches while still maintaining compatibility. It also assures that your workflow should still work.
Using the default branch of an action may be convenient, but if someone releases a new major version with a breaking change, your workflow could break.

Some actions require inputs that you must set using thewithkeyword. Review the action's README file to determine the inputs required.

runs:
using:"composite"
steps:
# Reference a specific commit
-uses:actions/checkout@8f4b7f84864484a7bf31766abe9204da3cbe65b3
# Reference the major version of a release
-uses:actions/checkout@v4
# Reference a specific version
-uses:actions/[email protected]
# Reference a branch
-uses:actions/checkout@main
# References a subdirectory in a public GitHub repository at a specific branch, ref, or SHA
-uses:actions/aws/ec2@main
# References a local action
-uses:./.github/actions/my-action
# References a docker public registry action
-uses:docker://gcr.io/cloud-builders/gradle
# Reference a docker image published on docker hub
-uses:docker://alpine:3.8

`runs.steps[*].with`

OptionalAmapof the input parameters defined by the action. Each input parameter is a key/value pair. For more information, seeExample: Specifying inputs.

runs:
using:"composite"
steps:
-name:Myfirststep
uses:actions/hello_world@main
with:
first_name:Mona
middle_name:The
last_name:Octocat

`runs`for Docker container actions

RequiredConfigures the image used for the Docker container action.

Example: Using a Dockerfile in your repository

runs:
using:'docker'
image:'Dockerfile'

Example: Using public Docker registry container

runs:
using:'docker'
image:'docker://debian:stretch-slim'

`runs.using`for Docker container actions

RequiredYou must set this value to'docker'.

`runs.pre-entrypoint`

OptionalAllows you to run a script before theentrypointaction begins. For example, you can usepre-entrypoint:to run a prerequisite setup script. GitHub Actions usesdocker runto launch this action, and runs the script inside a new container that uses the same base image. This means that the runtime state is different from the mainentrypointcontainer, and any states you require must be accessed in either the workspace,HOME,or as aSTATE_variable. Thepre-entrypoint:action always runs by default but you can override this usingruns.pre-if.

The runtime specified with theusingsyntax will execute this file.

In this example, thepre-entrypoint:action runs a script calledsetup.sh:

runs:
using:'docker'
image:'Dockerfile'
args:
-'bzz'
pre-entrypoint:'setup.sh'
entrypoint:'main.sh'

`runs.image`

RequiredThe Docker image to use as the container to run the action. The value can be the Docker base image name, a localDockerfilein your repository, or a public image in Docker Hub or another registry. To reference aDockerfilelocal to your repository, the file must be namedDockerfileand you must use a path relative to your action metadata file. Thedockerapplication will execute this file.

`runs.env`

OptionalSpecifies a key/value map of environment variables to set in the container environment.

`runs.entrypoint`

OptionalOverrides the DockerENTRYPOINTin theDockerfile,or sets it if one wasn't already specified. Useentrypointwhen theDockerfiledoes not specify anENTRYPOINTor you want to override theENTRYPOINTinstruction. If you omitentrypoint,the commands you specify in the DockerENTRYPOINTinstruction will execute. The DockerENTRYPOINTinstruction has ashellform andexecform. The DockerENTRYPOINTdocumentation recommends using theexecform of theENTRYPOINTinstruction.

For more information about how theentrypointexecutes, see "Dockerfile support for GitHub Actions."

`runs.post-entrypoint`

OptionalAllows you to run a cleanup script once theruns.entrypointaction has completed. GitHub Actions usesdocker runto launch this action. Because GitHub Actions runs the script inside a new container using the same base image, the runtime state is different from the mainentrypointcontainer. You can access any state you need in either the workspace,HOME,or as aSTATE_variable. Thepost-entrypoint:action always runs by default but you can override this usingruns.post-if.

runs:
using:'docker'
image:'Dockerfile'
args:
-'bzz'
entrypoint:'main.sh'
post-entrypoint:'cleanup.sh'

`runs.args`

OptionalAn array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. GitHub passes theargsto the container'sENTRYPOINTwhen the container starts up.

Theargsare used in place of theCMDinstruction in aDockerfile.If you useCMDin yourDockerfile,use the guidelines ordered by preference:

Document required arguments in the action's README and omit them from theCMDinstruction.
Use defaults that allow using the action without specifying anyargs.
If the action exposes a--helpflag, or something similar, use that to make your action self-documenting.

If you need to pass environment variables into an action, make sure your action runs a command shell to perform variable substitution. For example, if yourentrypointattribute is set to"sh -c",argswill be run in a command shell. Alternatively, if yourDockerfileuses anENTRYPOINTto run the same command ("sh -c"),argswill execute in a command shell.

For more information about using theCMDinstruction with GitHub Actions, see "Dockerfile support for GitHub Actions."

Example: Defining arguments for the Docker container

runs:
using:'docker'
image:'Dockerfile'
args:
-${{inputs.greeting}}
-'foo'
-'bar'

`branding`

OptionalYou can use a color andFeathericon to create a badge to personalize and distinguish your action. Badges are shown next to your action name inGitHub Marketplace.

Example: Configuring branding for an action

branding:
icon:'award'
color:'green'

coffee
columns
divide-circle
divide-square
divide
frown
hexagon
key
meh
mouse-pointer
smile
tool
x-octagon

Exhaustive list of all currently supported icons

activity
airplay
alert-circle
alert-octagon
alert-triangle
align-center
align-justify
align-left
align-right
anchor
aperture
archive
arrow-down-circle
arrow-down-left
arrow-down-right
arrow-down
arrow-left-circle
arrow-left
arrow-right-circle
arrow-right
arrow-up-circle
arrow-up-left
arrow-up-right
arrow-up
at-sign
award
bar-chart-2
bar-chart
battery-charging
battery
bell-off
bell
bluetooth
bold
book-open
book
bookmark
box
briefcase
calendar
camera-off
camera
cast
check-circle
check-square
check
chevron-down
chevron-left
chevron-right
chevron-up
chevrons-down
chevrons-left
chevrons-right
chevrons-up
circle
clipboard
clock
cloud-drizzle
cloud-lightning
cloud-off
cloud-rain
cloud-snow
cloud
code
command
compass
copy
corner-down-left
corner-down-right
corner-left-down
corner-left-up
corner-right-down
corner-right-up
corner-up-left
corner-up-right
cpu
credit-card
crop
crosshair
database
delete
disc
dollar-sign
download-cloud
download
droplet
edit-2
edit-3
edit
external-link
eye-off
eye
fast-forward
feather
file-minus
file-plus
file-text
file
film
filter
flag
folder-minus
folder-plus
folder
gift
git-branch
git-commit
git-merge
git-pull-request
globe
grid
hard-drive
hash
headphones
heart
help-circle
home
image
inbox
info
italic
layers
layout
life-buoy
link-2
link
list
loader
lock
log-in
log-out
mail
map-pin
map
maximize-2
maximize
menu
message-circle
message-square
mic-off
mic
minimize-2
minimize
minus-circle
minus-square
minus
monitor
moon
more-horizontal
more-vertical
move
music
navigation-2
navigation
octagon
package
paperclip
pause-circle
pause
percent
phone-call
phone-forwarded
phone-incoming
phone-missed
phone-off
phone-outgoing
phone
pie-chart
play-circle
play
plus-circle
plus-square
plus
pocket
power
printer
radio
refresh-ccw
refresh-cw
repeat
rewind
rotate-ccw
rotate-cw
rss
save
scissors
search
send
server
settings
share-2
share
shield-off
shield
shopping-bag
shopping-cart
shuffle
sidebar
skip-back
skip-forward
slash
sliders
smartphone
speaker
square
star
stop-circle
sun
sunrise
sunset
table
tablet
tag
target
terminal
thermometer
thumbs-down
thumbs-up
toggle-left
toggle-right
trash-2
trash
trending-down
trending-up
triangle
truck
tv
type
umbrella
underline
unlock
upload-cloud
upload
user-check
user-minus
user-plus
user-x
user
users
video-off
video
voicemail
volume-1
volume-2
volume-x
volume
watch
wifi-off
wifi
wind
x-circle
x-square
x
zap-off
zap
zoom-in
zoom-out

Metadata syntax for GitHub Actions

In this article