Action metadata is the required YAML manifest that lets GitHub identify an action and describes how it is used. The file must be named action.yml or action.yaml; its fixed name means an action belongs in its own repository or in a folder within a repository. The runs section declares the action type: Docker container, JavaScript, or composite. Docker actions run only on Linux, while JavaScript and composite actions can run on any platform. section 4.1 section 4.2.2
Use the manifest as the action’s consumer-facing contract. Give the action a name and description, define inputs and outputs, then specify the runtime under runs. For a Docker action built from a Dockerfile, using: docker and image: Dockerfile select the runtime; args can pass an input expression into the container. section 4.3.3
Listing 4.4 Writing the action.yml file that defines the action
name: "{GitHub username}'s Action in Action"
description: 'Greets someone and returns always 42.'
inputs:
who-to-greet: # id of input
description: 'Who to greet'
required: true
default: 'World'
outputs:
answer: # id of output
description: 'The answer to everything (always 42)'
runs:
using: 'docker'
image: 'Dockerfile'
args:
- ${{ inputs.who-to-greet }}
This manifest defines a Docker action with a required who-to-greet input, an answer output, and an argument forwarded into the container. section 4.3.3
Place and maintain metadata deliberately:
- Keep an action in its own repository when it needs an independent lifecycle or Marketplace publication; use folders to group related actions that share dependencies and versioning. section 4.2.2
- For Marketplace publication, put action.yml at the root of a public repository. GitHub detects it and checks publication properties such as name, description, branding, and README.md. section 4.4.2
- Document inputs and outputs clearly, avoid required inputs when possible, and supply defaults to make the action easier to consume. section 4.6
Docker greeting action
A practical manifest can expose who-to-greet with a default of World, return an answer output, and pass ${{ inputs.who-to-greet }} through args. A workflow then invokes the released action with uses, supplies who-to-greet under with, and reads the answer through steps.action.outputs.answer. section 4.3.3 section 4.4.2
Marketplace branding is metadata too: add a branding block with an icon and color before releasing. Pair that configuration with semantic versioning, moving a major-version tag to patched releases, and a README that explains use and contribution. section 4.4.2 section 4.6
