Metadata syntax for GitHub Actions

You can create actions to perform tasks in your repository. Actions require a metadata file that uses YAML syntax.

GitHub Actions is available with GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server, and GitHub One. GitHub Actions is not available for private repositories owned by accounts using legacy per-repository plans.

In this article

Note: GitHub Actions support on GitHub Enterprise Server 2.22 is a limited public beta. To review the external storage requirements and request access to the beta, see "Enabling GitHub Actions and configuring storage."

Note: GitHub-hosted runners are not currently supported on GitHub Enterprise Server. You can see more information about planned future support on the GitHub public roadmap.

About YAML syntax for GitHub Actions

Docker and JavaScript actions require a metadata file. The metadata filename must be either action.yml or action.yaml. The data in the metadata file defines the inputs, outputs and main entrypoint for your action.

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

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. Input ids with uppercase letters are converted to lowercase during runtime. We recommended using lowercase input ids.

Example

This example configures two inputs: numOctocats and octocatEyeColor. The numOctocats input is not required and will default to a value of '1'. The octocatEyeColor input is required and has no default value. Workflow files that use this action must use the with keyword to set an input value for octocatEyeColor. For more information about the with syntax, see "Workflow syntax for GitHub Actions."

inputs:
  numOctocats:
    description: 'Number of Octocats'
    required: false
    default: '1'
  octocatEyeColor:
    description: 'Eye color of the Octocats'
    required: true

When you specify an input to an action in a workflow file or use a default input value, 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.

For example, if a workflow defined the numOctocats and octocatEyeColor inputs, the action code could read the values of the inputs using the INPUT_NUMOCTOCATS and INPUT_OCTOCATEYECOLOR 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

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

outputs

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.

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

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 _.

outputs.<output_id>.description

Required A string description of the output parameter.

outputs for composite run steps actions

Optional outputs use the same parameters as outputs.<output_id> and outputs.<output_id>.description (see "outputs for GitHub Actions"), but also includes the value token.

Example

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

outputs.<output_id.value>

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

For more information on how to use context and expression syntax, see "Context and expression syntax for GitHub Actions".

runs for JavaScript actions

Required Configures the path to the action's code and the application used to execute the code.

Example using Node.js

runs:
  using: 'node12'
  main: 'main.js'

runs.using

Required The application used to execute the code specified in main.

runs.main

Required The file that contains your action code. The application specified in using executes this file.

pre

Optional Allows you to run a script at the start of a job, before the main: action begins. For example, you can use pre: to run a prerequisite setup script. The application specified with the using syntax will execute this file. The pre: action always runs by default but you can override this using pre-if.

In this example, the pre: action runs a script called setup.js:

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

pre-if

Optional Allows you to define conditions for the pre: action execution. The pre: action will only run if the conditions in pre-if are met. If not set, then pre-if defaults to always(). Note that the step 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'

post

Optional Allows you to run a script at the end of a job, once the main: action has completed. For example, you can use post: to terminate certain processes or remove unneeded files. The application specified with the using syntax will execute this file.

In this example, the post: action runs a script called cleanup.js:

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

The post: action always runs by default but you can override this using post-if.

post-if

Optional Allows you to define conditions for the post: action execution. The post: action will only run if the conditions in post-if are met. If not set, then post-if defaults to always().

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

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

runs for composite run steps actions

Required Configures the path to the composite action, and the application used to execute the code.

runs.using

Required To use a composite run steps action, set this to "composite".

runs.steps

Required The run steps that you plan to run in this action.

runs.steps.run

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

runs:
  using: "composite"
  steps: 
    - run: $/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 "github context".

runs.steps.shell

Required The shell where you want to run the command. You can use any of the shells listed here.

runs.steps.name

Optional The name of the composite run step.

runs.steps.id

Optional A unique identifier for the step. You can use the id to reference the step in contexts. For more information, see "Context and expression syntax for GitHub Actions".

runs.steps.env

Optional Sets a map of environment variables for only that step. If you want to modify the environment variable stored in the workflow, use echo "::set-env name={name}::{value}" in a composite run step.

runs.steps.working-directory

Optional Specifies the working directory where the command is run.

runs for Docker actions

Required Configures the image used for the Docker 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

Required You must set this value to 'docker'.

pre-entrypoint

Optional Allows you to run a script before the entrypoint action begins. For example, you can use pre-entrypoint: to run a prerequisite setup script. GitHub Actions uses docker 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 main entrypoint container, and any states you require must be accessed in either the workspace, HOME, or as a STATE_ variable. The pre-entrypoint: action always runs by default but you can override this using pre-if.

The application specified with the using syntax will execute this file.

In this example, the pre-entrypoint: action runs a script called setup.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 local Dockerfile in your repository, or a public image in Docker Hub or another registry. To reference a Dockerfile local to your repository, use a path relative to your action metadata file. The docker 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 Docker ENTRYPOINT in the Dockerfile, or sets it if one wasn't already specified. Use entrypoint when the Dockerfile does not specify an ENTRYPOINT or you want to override the ENTRYPOINT instruction. If you omit entrypoint, the commands you specify in the Docker ENTRYPOINT instruction will execute. The Docker ENTRYPOINT instruction has a shell form and exec form. The Docker ENTRYPOINT documentation recommends using the exec form of the ENTRYPOINT instruction.

For more information about how the entrypoint executes, see "Dockerfile support for GitHub Actions."

post-entrypoint

Optional Allows you to run a cleanup script once the runs.entrypoint action has completed. GitHub Actions uses docker 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 main entrypoint container. You can access any state you need in either the workspace, HOME, or as a STATE_ variable. The post-entrypoint: action always runs by default but you can override this using 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 the args to the container's ENTRYPOINT when the container starts up.

The args are used in place of the CMD instruction in a Dockerfile. If you use CMD in your Dockerfile, use the guidelines ordered by preference:

  1. Document required arguments in the action's README and omit them from the CMD instruction.
  2. Use defaults that allow using the action without specifying any args.
  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 your entrypoint attribute is set to "sh -c", args will be run in a command shell. Alternatively, if your Dockerfile uses an ENTRYPOINT to run the same command ("sh -c"), args will execute in a command shell.

For more information about using the CMD instruction with GitHub Actions, see "Dockerfile support for GitHub Actions."

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

branding

You can use a color and Feather icon to create a badge to personalize and distinguish your action. Badges are shown next to your action name in GitHub Marketplace.

Example

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

branding.color

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

branding.icon

The name of the Feather icon to use.

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

Did this doc help you?

Privacy policy

Help us make these docs great!

All GitHub docs are open source. See something that's wrong or unclear? Submit a pull request.

Make a contribution

Or, learn how to contribute.