Build a Definition

A Definition captures an operational procedure in YAML. It contains the inputs the caller supplies and an ordered list of steps. Each step uses an existing Action; writing the Definition does not require writing Python.

Start with the operation

Identify the intended effect, the checks needed before it, and how to verify the outcome. Choose Actions with documented contracts, external permissions, and retry behavior. Confirm they are available through the target Environment's registry before deploying.

The following illustrative service remediation Definition assumes three Actions with the contracts shown. These names are not claims of published official Actions; substitute integrations available in your installation.

apiVersion: pyplines/v1
kind: Definition
name: service-health
inputs:
  service:
    type: string
    required: true
steps:
  - name: inspect
    uses: inspect-service@2026.10.1
    with:
      service: "${{ inputs.service }}"
      endpoint: "${{ context.service_api }}"
  - name: restart
    uses: restart-service@2026.10.1
    when: "${{ steps.inspect.outputs.healthy == false }}"
    with:
      service_id: "${{ steps.inspect.outputs.service_id }}"
      token: "${{ secrets.service_api_token }}"
  - name: verify
    uses: verify-service@2026.10.1
    with:
      service: "${{ inputs.service }}"
      endpoint: "${{ context.service_api }}"

Here inspect-service must return a boolean healthy and a string service_id. restart-service must accept service_id and token. verify-service must fail if health does not meet the desired condition: merely returning healthy: false is not enough to block a Run automatically.

Connect inputs and outputs

with maps values to the selected Action's input fields. A whole expression such as ${{ inputs.service }} preserves the referenced JSON type. A step can reference only earlier steps.

Keep configuration outside the Definition when it changes by deployment location. Use public Environment context for endpoints and Environment secrets for credentials. See inputs, context, and secrets.

Control whether a step runs

when must evaluate to a boolean. A false condition skips the step before its inputs are resolved. A skipped step has status skipped and no outputs. Referencing those missing outputs blocks the receiving step; they do not become null.

In the example, verify uses the original service input, so it can execute whether restart succeeded or was skipped. If restart fails, the Run blocks before verification until an authorized recovery decision is made.

Validate and deploy

pyplines validate ./service-health.yaml
pyplines deploy ./service-health.yaml --environment development

Local validation checks structure. Deployment validates expressions and available Action contracts, then pins image digests. Preparation validates values only known at execution time. Passing local validation alone does not establish that a workflow is deployable or that external credentials work.

Approvals and access rules are configured separately from the Definition. Continue with deployments and revisions and the Definition reference.