feat: name runs with a CEL display-name expression on the workflow/task definition (#4259)

[Mdev303]

Name runs with a human-readable label by declaring a CEL expression on the workflow and/or task definition. The engine evaluates it against each run's input at trigger time and stores the result as the run/step display name. Because the expression lives in the definition, every trigger source — manual, run_many/bulk, child spawn, event, and cron — produces meaningful names automatically, and DAG steps can be named independently.

Fixes #4259

How it works

The whole string is evaluated as one CEL expression (consistent with concurrency and rate-limit keys — there is no {{ }} templating):

• Reference run input with input.<key>, e.g. input.customerName.
• Quote string literals as CEL strings, e.g. 'Acme Corp'.
• Guard optional keys with has(), e.g. has(input.name) ? input.name : 'run'.

Levels & precedence

• A workflow-level expression names the run — the DAG run for a multi-step workflow, or the task for a single-task workflow (the task is the run).
• A per-task expression names an individual DAG step.
• On a single-task workflow the precedence is: task expression → workflow expression → generated fallback.

Failures never fail the run. A malformed expression is rejected at registration (via the celworkflowrunstr validator). At run time, any evaluation error — missing key, non-string result, or empty result — silently falls back to the generated <readableId|name>-<timestamp> label. A result longer than 255 characters is stored truncated (rune-safe), never rejected.

Usage

Set the expression on the workflow and/or task definition — it applies to every run regardless of trigger source.

Python

customer_workflow = hatchet.workflow(
    name="CustomerWorkflow",
    display_name="input.customerName",   # names the run
)

@customer_workflow.task(display_name="'enrich-' + input.customerName")  # names this DAG step
def enrich(input: WorkflowInput, ctx: Context) -> None: ...

TypeScript

const customerWorkflow = hatchet.workflow({
  name: "customer-workflow",
  displayName: "input.customerName",
});

customerWorkflow.task({ name: "enrich", displayName: "'enrich-' + input.customerName", fn });

Go

wf := client.NewWorkflow("customer-workflow", hatchet.WithWorkflowDisplayName("input.customerName"))
wf.NewTask("enrich", enrichFn, hatchet.WithDisplayName("'enrich-' + input.customerName"))

Ruby

wf = hatchet.workflow(name: "CustomerWorkflow", display_name: "input.customerName")
wf.task(name: "enrich", display_name: "'enrich-' + input.customerName") { |input, ctx| ... }

Design decisions & trade-offs

• CEL on the definition, not a literal at trigger time. One declaration names every run of the workflow across all trigger sources (manual/bulk/child/event/cron), and enables independent per-step names — neither of which the trigger-time literal could do.
• Pure CEL (whole string). Consistent with concurrency and rate-limit keys; no bespoke {{ }} templating to learn or maintain.
• Input-only environment (input, additional_metadata, workflow_run_id) — no parent-step outputs, keeping evaluation available at trigger time.
• Validated at registration, silent at runtime. A bad expression is caught when you register the workflow (celworkflowrunstr); a runtime failure (missing key / non-string / empty) never fails the run — it falls back to the generated name. >255 runes → truncated (rune-safe), never rejected.
• Versioned. The expressions are folded into the workflow-version checksum, so changing an expression produces a new version.
• Backward compatible. Both display_name fields are optional; omitting them reproduces today's exact generated-name behavior.

What's changed

• Contracts: removed the trigger-time display_name (TriggerWorkflowRequest Feat: introduce a scheduling state #11, TriggerWorkflowRunRequest chore(contributing): adapt deps, hardcode generator versions #6) and marked both field numbers/names reserved; added CreateWorkflowVersionRequest.display_name (chore(frontend): setup eslint and prettier with better defaults #15) and CreateTaskOpts.display_name (chore: add docker builds #16). OpenAPI trigger body field removed. All generated code (Go, REST, frontend, and all 4 SDK proto stubs) regenerated.
• Storage: nullable displayName columns on WorkflowVersion and Step (migration 20260721120000_v1_0_126) + sqlc regen; opts tagged celworkflowrunstr and folded into the version checksum.
• Engine eval: pure resolveDisplayName helper; workflow-level expr evaluated in createDAGs → v1_dag.display_name, step/workflow expr evaluated in insertTasks → v1_task.display_name, with silent fallback + NormalizeDisplayName (trim + 255-rune truncate).
• admin service: req.DisplayName / step DisplayName threaded through getCreateWorkflowOpts / getCreateTaskOpts so definition expressions reach the repository via normal gRPC PutWorkflow.
• SDKs (Go, TypeScript, Python, Ruby): definition-level display_name on the workflow and task builders (mirroring concurrency), threaded into CreateWorkflowVersionRequest / CreateTaskOpts; all trigger-time run-call surfaces removed.
• Docs / changelog: run-names.mdx rewritten for the CEL mechanism; root + per-SDK changelogs updated.

Type of change

• New feature (non-breaking change which adds functionality)

Checklist

• Tested — resolveDisplayName unit tests, checksum cases, admin-service conversion regression tests (getCreateWorkflowOpts/getCreateTaskOpts), per-SDK definition-threading tests (Go 4, TS 9, Python 5, Ruby 7), and a 13-case CEL integration suite run against live Postgres + RabbitMQ (single-task/DAG, step-vs-workflow precedence, event-triggered runs, fan-out distinct names, fallbacks, 255-rune truncation, invalid-expr rejection).
• Linted / type-checked (Go vet, tsc + eslint, mypy + ruff, Ruby specs).
• Documented (Run Names guide rewritten).
• Added to CHANGELOG (root + per-SDK).

🤖 AI Disclosure

• I acknowledge that an LLM was used in the creation of this Pull Request, in accordance with Hatchet's AI_POLICY.md.

• Details: Implemented with Claude Code reviewed by me

[vercel]

@Mdev303 is attempting to deploy a commit to the Hatchet Team on Vercel.

A member of the Team first needs to authorize it.

[Mdev303]

I will fix the conflicts once I get a review , it's mostly changelog stuff or the proto regen

[abelanger5]

Hi @Mdev303, thanks for the PR! I think it would be cleaner to use CEL-based templating instead of trigger-based arguments, for the following reasons:

1. It would allow us to set display names on specific steps more easily
2. It would allow for display names when triggering from events or dynamically registered crons
3. It's consistent with how other configuration is written on a per-step basis; priority is one of the exceptions, but even that has a per-step default.

I'm not strictly opposed to trigger-based overrides, but I think I prefer CEL-based for this initial scope. Trigger-based is always possible by just setting a displayName on the input.

[Mdev303]

@abelanger5 Thanks for the review ! I made the change it now uses CEL based templating ( I also updated the PR title and description )

I also tested with python and TS sdk manually

let me know if there is anything else