Build your first Action

Custom Actions extend the operations your team can automate. This guide is for integration authors. To use existing Actions or deployed workflows, start with Run your first workflow.

Prerequisites

Install the pyplines-action binary for your operating system and architecture from the matching GitHub release. Put it on your PATH and check pyplines-action version.

With pyplines-installer installed, create an Action tooling configuration and apply it:

pyplines-installer init --preset action --output action-tools.yml
pyplines-installer run action-tools.yml
pyplines-action version

See Action CLI installation for tooling version selection, authentication, and PATH setup.

Local development also requires Docker Engine or Desktop with Buildx, uv (tested with 0.12.18), and Python 3.14. The Docker daemon must have access to the same filesystem paths as the CLI.

Create the project

pyplines-action init ./hello-world

The command creates the project and generates uv.lock. Commit both pyproject.toml and uv.lock. The Action's declared SDK requirement and lock select its runtime bases.

Write the handler

Replace src/hello_world/__init__.py with the handler below, and save the input file in the project directory. The highlighted lines declare the input and output contracts.

from pyplines.actions import Context, Inputs, Outputs

class HelloInputs(Inputs):
    name: str

class HelloOutputs(Outputs):
    greeting: str

def handler(inputs: HelloInputs, context: Context) -> HelloOutputs:
    context.log("Preparing greeting")
    return HelloOutputs(greeting=f"Hello, {inputs.name}!")

{"name": "Engineer"}

The scaffold declares the handler entry point in pyproject.toml. The input file supplies the name field declared by HelloInputs.

Run locally

pyplines-action run ./hello-world --input ./hello-world/input.json

{"greeting": "Hello, Engineer!"}

Successful output contains {"greeting":"Hello, Engineer!"}. Action logs go to stderr; redirected stdout contains the output JSON object.

Validate the packaged Action

pyplines-action run ./hello-world --input ./hello-world/input.json --packaged
pyplines-action validate ./hello-world

Packaged execution tests the installed Action. Validation builds the image and captures its typed interface. Continue with local development and publishing.