name

Required The name of your action. GitHub displays thename in theActions 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 andoctocat-eye-color. Thenum-octocats input is not required and will default to a value of1.octocat-eye-color is required and has no default value.

Workflow files that use this action can use thewith keyword to set an input value foroctocat-eye-color. For more information about thewith syntax, seeWorkflow syntax for GitHub Actions.

inputs:num-octocats:description:'Number of Octocats'required:falsedefault:'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 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>. With composite actions you can useinputsContexts reference to access action inputs.

To access the environment variable in a Docker container action, you must pass the input using theargs keyword in the action metadata file. For more information about the action metadata file for Docker container actions, seeCreating a Docker container action.

For example, if a workflow defined thenum-octocats andoctocat-eye-color inputs, the action code could read the values of the inputs using theINPUT_NUM-OCTOCATS andINPUT_OCTOCAT-EYE-COLOR environment variables.

inputs.<input_id>

Required Astring 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 theinputs object. The<input_id> must start with a letter or_ and contain only alphanumeric characters,-, or_.

inputs.<input_id>.description

Required Astring description of the input parameter.

inputs.<input_id>.required

Optional Aboolean to indicate whether the action requires the input parameter. Set totrue when the parameter is required.

inputs.<input_id>.default

Optional Astring 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, thisstring 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, seeWorkflow commands for GitHub Actions.

Example: Declaring outputs for Docker container and JavaScript actions

outputs:sum:# id of the outputdescription:'The sum of the inputs'

outputs.<output_id>

Required Astring 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 theoutputs object. The<output_id> must start with a letter or_ and contain only alphanumeric characters,-, or_.

outputs.<output_id>.description

Required Astring description of the output parameter.

outputs for composite actions

Optionaloutputs use the same parameters asoutputs.<output_id> andoutputs.<output_id>.description (seeoutputs for Docker container and JavaScript actions), but also includes thevalue token.

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.

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-generatorrun:echo"random-id=$(echo $RANDOM)">>$GITHUB_OUTPUTshell:bash

outputs.<output_id>.value

Required The value that the output parameter will be mapped to. You can set this to astring or an expression with context. For example, you can use thesteps context to set thevalue of an output to the output value of a step.

For more information on how to use context syntax, seeContexts reference.

runs

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

runs for JavaScript actions

Required Configures 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

Required The runtime used to execute the code specified inmain.

• Usenode20 for Node.js v20.

runs.main

Required The file that contains your action code. The runtime specified inusing executes this file.

runs.pre

Optional Allows 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 theusing syntax 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

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

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

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

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

runs.post

Optional Allows 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 theusing syntax 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

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

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

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

runs for composite actions

Required Configures the path to the composite action.

runs.using for composite actions

Required You must set this value to'composite'.

runs.steps

Required The steps that you plan to run in this action. These can be eitherrun steps oruses steps.

runs.steps[*].run

Optional The 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.shshell:bash

Alternatively, you can use$GITHUB_ACTION_PATH:

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

For more information, seeContexts reference.

runs.steps[*].shell

Optional The shell where you want to run the command. You can use any of the shells listed inWorkflow syntax for GitHub Actions. Required ifrun is set.

runs.steps[*].if

Optional You can use theif conditional 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 anif conditional, you can, optionally, omit the${{ }} expression syntax because GitHub Actions automatically evaluates theif conditional 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, seeEvaluate expressions in workflows and actions.

Example: Using contexts

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

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

Example: Using status check functions

Themy backup step only runs when the previous step of a composite action fails. For more information, seeEvaluate expressions in workflows and actions.

steps:-name:Myfirststepuses:octo-org/action-name@main-name:Mybackupstepif:${{failure()}}uses:actions/heroku@1.0.0

runs.steps[*].name

Optional The name of the composite step.

runs.steps[*].id

Optional A unique identifier for the step. You can use theid to reference the step in contexts. For more information, seeContexts reference.

runs.steps[*].env

Optional Sets amap of environment variables for only that step. If you want to modify the environment variable stored in the workflow, useecho "{name}={value}" >> $GITHUB_ENV in a composite step.

runs.steps[*].working-directory

Optional Specifies the working directory where the command is run.

runs.steps[*].uses

Optional Selects 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 thewith keyword. 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/checkout@v4.2.0# 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

Optional Amap of 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:Myfirststepuses:actions/hello_world@mainwith:first_name:Monamiddle_name:Thelast_name:Octocat

runs.steps[*].continue-on-error

Optional Prevents the action from failing when a step fails. Set totrue to allow the action to pass when this step fails.

runs for Docker container actions

Required Configures 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

Required You must set this value to'docker'.

runs.pre-entrypoint

Optional Allows you to run a script before theentrypoint action begins. For example, you can usepre-entrypoint: to run a prerequisite setup script. GitHub Actions usesdocker run to 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 mainentrypoint container, 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 theusing syntax 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

Required The Docker image to use as the container to run the action. The value can be the Docker base image name, a localDockerfile in your repository, or a public image in Docker Hub or another registry. To reference aDockerfile local to your repository, the file must be namedDockerfile and you must use a path relative to your action metadata file. Thedocker application will execute this file.

runs.env

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

runs.entrypoint

Optional Overrides the DockerENTRYPOINT in theDockerfile, or sets it if one wasn't already specified. Useentrypoint when theDockerfile does not specify anENTRYPOINT or you want to override theENTRYPOINT instruction. If you omitentrypoint, the commands you specify in the DockerENTRYPOINT instruction will execute. The DockerENTRYPOINT instruction has ashell form andexec form. The DockerENTRYPOINT documentation recommends using theexec form of theENTRYPOINT instruction.

For more information about how theentrypoint executes, seeDockerfile support for GitHub Actions.

runs.post-entrypoint

Optional Allows you to run a cleanup script once theruns.entrypoint action has completed. GitHub Actions usesdocker run to 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 mainentrypoint container. 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

Optional An array of strings that define the inputs for a Docker container. Inputs can include hardcoded strings. GitHub passes theargs to the container'sENTRYPOINT when the container starts up.

Theargs are used in place of theCMD instruction in aDockerfile. If you useCMD in yourDockerfile, use the guidelines ordered by preference:

1. Document required arguments in the action's README and omit them from theCMD instruction.
2. Use defaults that allow using the action without specifying anyargs.
3. If the action exposes a--help flag, 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 yourentrypoint attribute is set to"sh -c",args will be run in a command shell. Alternatively, if yourDockerfile uses anENTRYPOINT to run the same command ("sh -c"),args will execute in a command shell.

For more information about using theCMD instruction with GitHub Actions, seeDockerfile support for GitHub Actions.

Example: Defining arguments for the Docker container

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

branding

Optional You can use a color andFeather icon 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'

branding.color

The background color of the badge. Can be one of:white,black,yellow,blue,green,orange,red,purple, orgray-dark.

branding.icon

The name of the v4.28.0Feather icon to use.

Omitted icons

Brand icons, and all the following icons, are omitted.

• 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

Changing the metadata file name

While the actions metadata file supports both YAML formats, changing the metadata file name (fromaction.yml toaction.yaml or vice versa) between releases will affect previous release versions that have been published to GitHub Marketplace. Changing the file name will hide all release versions associated with the previous file name from GitHub Marketplace. Previous release versions will still be accessible to users through the source repository.

When releasing new versions of actions, only versions released after the metadata file name change will have the GitHub Marketplace tag and will show up on GitHub Marketplace