Local development

Fast and packaged execution

For conventional setuptools src/ projects, run caches dependencies and mounts a read-only source snapshot into a fresh container. Source or input edits do not rebuild the dependency image.

Use --packaged when your Action needs installed package metadata, installation hooks, or a packaging layout that cannot use the fast path. validate and push always use packaged builds.

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

Dependencies

Commit uv.lock. Missing or stale locks fail preparation; a run does not update them. Update dependencies intentionally with uv, then run and validate again. An exact SDK pin must also be edited when upgrading beyond that version.

cd hello-world
uv lock --upgrade-package pyplines
pyplines-action run . --input input.json
pyplines-action validate .

--refresh refreshes base resolution and rebuilds dependencies. --local-bases is for SDK development from a source checkout, using the SDK embedded in the locally built CLI.

For SDK development, build the CLI with task build at the repository root; task version shows its Git-derived tooling version. Build the SDK wheel with uv build pyplines-sdk, pin the Action to that exact version, and lock against the wheel using uv lock --find-links <wheel-directory> --python 3.14. Development SDK versions require --local-bases and must match the SDK embedded in the CLI. Rebuild both after changing the SDK. Installed release CLIs continue to resolve their published SDK bases normally.

Diagnostics

Detailed local diagnostics show bounded tracebacks and field-level validation errors. --diagnostics concise suppresses these details. --verbose independently enables build and cache diagnostics.

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

JSON mode emits JSON Lines, including action.log and one terminal action.result. Exception messages and source lines can contain sensitive information; avoid detailed diagnostics for sensitive inputs.

Runtime limits

• The complete serialized input envelope, including metadata and escaping, must fit within 256 KiB.
• Preparation has a separate 20-minute deadline. Execution uses the Action's timeout_seconds budget.
• Network access is opt-in. An Action declaring it requires an explicit --network for local execution.
• Source and inputs are read-only mounts readable by runtime UID 65532, including with a restrictive host umask.
• A local Docker daemon or shared client/daemon paths are required. Remote file staging is not supported.