Document per-execution Hub worktree branch names (#3267)

jb/paseo

* docs(hub): document per-execution worktree branch names

Hub now materializes `${{ paseo.execution.id }}` inside a daemon
environment's `worktree.newBranch` before it persists or dispatches the
launch, so a reusable branch-off environment can get a stable branch per
execution instead of every trigger contending for one literal name.

The reference states the constraint precisely because it is the part the
YAML cannot show: `newBranch` accepts that one execution-scoped path and
nothing else, and any other expression fails bundle activation with the
authored file and field in the error. Literal branch names stay valid.

* docs(hub): reshape the per-execution worktree branch docs

Split the two pages by the job each reader is doing. The daemon page is a
task guide, so it now carries the worktree YAML and only the two facts
that reader needs to choose a branch name, then links out. The reference
owns the exhaustive contract at the `newBranch` field: a table contrasting
a literal with the template, then the accepted expression scope and what
activation rejects.

Dropped the render-before-dispatch ordering. Readers cannot act on where
Hub materializes the value; the reachable behavior is that a retried or
recovered execution keeps its branch, which is what the table says.

* docs(hub): make the per-execution worktree branch the only guidance

A branch-off Hub environment that aims every execution at one branch name
is not a configuration worth teaching, so the docs no longer present it as
an alternative. Both pages now show `newBranch: trigger-${{ paseo.execution.id }}`
and say what it does, with no literal-branch example and no comparison.

The reference keeps the field's type as a bare syntax fact, along with the
accepted expression, what activation rejects, and the authored field the
failure names.

This commit is contained in:

Mohamed Boudra

2026-08-12 18:20:08 +08:00

committed by

GitHub

parent 74f2158c45

commit 6ed364ffe2

2 changed files with 13 additions and 3 deletions

									
										public-docs/hub/daemons.md
									
		+4
		-2
	
												View File
												
				@@ -80,11 +80,13 @@ To keep executions off your working tree, add a worktree:

				```yaml

				worktree:

				  mode: branch-off

				  newBranch: hub/investigation

				  newBranch: trigger-${{ paseo.execution.id }}

				  base: origin/main

				```

				See [Git worktrees](/docs/worktrees) for setup hooks and scripts.

				`${{ paseo.execution.id }}` renders the execution's UUID, so every execution gets its own branch off `origin/main`.

				[Environment fields](/docs/hub/configuration/hub-yml#environments) lists what `newBranch` accepts. See [Git worktrees](/docs/worktrees) for setup hooks and scripts.

				## What Hub owns