Document per-execution Hub worktree branch names (#3267)
* 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:
@@ -72,10 +72,18 @@ environments:
|
||||
cwd: /workspace/project
|
||||
worktree:
|
||||
mode: branch-off
|
||||
newBranch: paseo/review
|
||||
newBranch: trigger-${{ paseo.execution.id }}
|
||||
base: origin/main
|
||||
```
|
||||
|
||||
`newBranch` is a branch-name string. Embed `${{ paseo.execution.id }}`, which renders the execution's UUID, so every execution branches off `base` on its own branch and keeps it when Hub retries or recovers that execution.
|
||||
|
||||
One execution is one step run, so two steps selecting the same environment get separate branches.
|
||||
|
||||
`${{ paseo.execution.id }}` is the only expression `newBranch` accepts. `paseo.prompt`, `paseo.context`, `paseo.inputs.*`, `values.*`, `steps.<id>.outputs.*`, and provider event fields are unavailable here, and each one fails bundle activation at the authored field, such as `.paseo/hub.yml.environments.review.worktree.newBranch`.
|
||||
|
||||
`${{ paseo.execution.id }}` fails activation the same way anywhere else in a bundle. `branch` and `prNumber` take literal values.
|
||||
|
||||
An environment is a complete named object. A step selects its name; objects are not inherited, merged, or partially overridden.
|
||||
|
||||
### Named agents
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user