Metadata syntax for GitHub Actions

Every custom GitHub Action must include a metadata file (action.yml or action.yaml) in the repository root. This file defines how GitHub recognizes, configures, and runs your Action.

Key Definitions

Basic Metadata Example

name: 'Hello Custom Action'
description: 'Greet someone and record the time'
author: 'Siddharth'
branding:
  icon: 'award'
  color: 'green'
inputs:
  who-to-greet:
    description: 'The person to greet'
    required: true
    default: 'Alice'
    deprecationMessage: 'This input will be removed in the next major version.'
outputs:
  time:
    description: 'Timestamp when greeting occurred'
runs:
  using: 'node20'

Inputs and Outputs

• inputs
  Define each parameter with:
  • description (required)
  • required (boolean)
  • Optional: default, deprecationMessage
• outputs
  Define each output with:
  • description (required)

JavaScript Action Metadata

Use this pattern when your Action runs on Node.js:

name: 'Hello JS Action'
description: 'Greets a user'
inputs:
  who-to-greet:
    description: 'Person to greet'
    required: true
outputs:
  time:
    description: 'Greeting timestamp'
runs:
  using: 'node20'           # node16 | node18 | node20, etc.
  pre: 'setup.js'           # Optional: runs before main
  pre-if: "runner.os == 'linux'"
  main: 'index.js'          # Entrypoint script
  post: 'cleanup.js'        # Optional: runs after main
  post-if: "runner.os == 'linux'"

• using: Node runtime version
• main: Primary entrypoint file
• pre / post: Setup and teardown scripts
• pre-if / post-if: Conditions for running pre/post scripts

Docker Container Action Metadata

Container Actions package dependencies in a Docker image:

name: 'Hello Docker Action'
description: 'Greets a user in a container'
inputs:
  who-to-greet:
    description: 'Person to greet'
    required: true
outputs:
  time:
    description: 'Greeting timestamp'
runs:
  using: 'docker'
  image: 'Dockerfile'         # Or registry reference: docker://alpine:3.8
  args:
    - ${{ inputs.who-to-greet }}
  pre-entrypoint: 'setup.sh'    # Optional script before container ENTRYPOINT
  entrypoint: 'main.sh'         # Overrides Dockerfile ENTRYPOINT
  post-entrypoint: 'cleanup.sh' # Optional script after entrypoint

• using: Must be docker
• image: Path to Dockerfile or registry image
• args: Array of arguments passed to the container
• pre-entrypoint / post-entrypoint: Hooks around the container’s entrypoint

Composite Action Metadata

Composite Actions let you chain shell commands and other Actions:

name: 'Hello Composite Action'
description: 'Greets a user with multiple steps'
inputs:
  who-to-greet:
    description: 'Person to greet'
    required: true
outputs:
  time:
    description: 'Greeting timestamp'
runs:
  using: 'composite'
  steps:
    - run: ./scripts/setup.sh
      shell: bash           # bash | sh | pwsh | python
    - run: echo "Hello, ${{ inputs.who-to-greet }}"
    - uses: docker://alpine:3.8
      with:
        entrypoint: /bin/sh

• using: Must be composite
• steps: List of step objects, each with run or uses
• Optional: shell to specify interpreter

Action Types Comparison

Links and References

• GitHub Actions Metadata Syntax
• Creating a JavaScript Action
• Implementing a Docker Container Action
• Composite Run Steps Action