Skip to main content

Defining an action

A composite action is its own YAML document with an id, optional inputs and outputs, and a steps block:

id: greet
name: Greet

inputs:
  name:
    type: string
    default: "world"

outputs:
  message:
    description: "The composed greeting"
    value: ${{ .steps.compose.outputs.message }}

steps:
  - id: compose
    env:
      NAME: ${{ .inputs.name }}
    run: echo "message=Hello, ${NAME}!" >> "$H2O_WORKFLOWS_OUTPUT"

Schema​

See Schema Reference for the #Action, #Output, and #Step (with uses/with) definitions.

inputs​

Typed parameters, identical to workflow inputs (string, bool, int, with required, default, description, and secret). Inside the action, an input is referenced as ${{ .inputs.<name> }} and resolves to the action's own inputs (not the calling workflow's).

outputs​

A map of named outputs the action exposes to its caller. Each output has an optional description and a required value, where value maps a step output to the action output using an expression:

outputs:
  message:
    description: "The composed greeting"
    value: ${{ .steps.compose.outputs.message }}

Action outputs are always strings. Only declared outputs are visible to the caller; the outputs of the action's steps are otherwise private. An output name must start with a letter, contain only letters, digits, and underscores, not end with an underscore, and be at most 63 characters.

steps​

An ordered list of steps. A step inside an action can be run, upload, or download. It cannot be uses: a composite action cannot call another composite action (see Nesting).

A step inside an action may carry an if condition, scoped to the action: it references the action's inputs, env, and the state and outputs of the action's earlier steps (steps.<id>.state, steps.<id>.outputs.<name>), with failure()/always() relative to those earlier steps. It cannot reference another job's state (deps.<id>) - an action has no job scope.

Emitting step outputs​

A step produces outputs by writing key=value lines to the file referenced by the $H2O_WORKFLOWS_OUTPUT environment variable, and tagging the step with an id:

steps:
  - id: compose
    run: echo "message=Hello, world!" >> "$H2O_WORKFLOWS_OUTPUT"

Those outputs are then available as ${{ .steps.compose.outputs.message }}. This mechanism is not specific to composite actions; see Step outputs and Expressions.

Nesting​

Nesting composite actions is not supported: a composite action's steps cannot reference another action with uses. A uses step is only valid directly within a job.

Feedback

Related content

Using an action
Step structure
Expressions