How worktrees work
A worktree is a working copy of one project, kept on one node. Each one is a slot. Every task runs inside a slot of its own.
Terms
| Term | Meaning |
|---|---|
| Slot | One worktree: a numbered working copy of a project on a node, for example #1. |
| Holder | The task a slot is held by. A slot nobody holds is free. |
| Stack | The project's local app stack, started inside the slot when the project has one. |
Each slot's stack gets its own ports: the node gives each of the project's Port vars a free port, and a slot keeps its port from one task to the next while no other slot on the node holds it. See Give a service a fixed port in every slot.
How a project gets slots
A project's slots live on its nodes: All, every enabled node of your organization, or the nodes of the node groups picked in the project's Settings tab, section Nodes. Jaah makes a slot for each task as it starts, with a fresh copy of the repository, and removes it when the task lets it go. No slot is kept ready between tasks. See Run a project on some nodes only. The node builds each slot itself. See How nodes work.
Changing a project's node groups never removes a slot in use: a running task finishes where it is.
Who holds a slot, and for how long
When a task starts, Jaah gives it a free slot of its project on a node that takes new tasks, and the runner works there.
A slot stays with its holder until the task is completed, deleted or reset, an operator releases it, or one of the other cases under Which node a task runs on lets it go. Stopping a task doesn't end the hold, so a task you stop and start again carries on with the work already in its slot. See How tasks work.
A node's details show how many slots it holds under Slots, and which tasks hold them under Held. See Nodes.
Which node a task runs on
A project isn't on one node: it's on every node of All, or of its node groups, all at once. Jaah chooses a node for each task on its own, preferring the least busy of the project's nodes that take new tasks. So one project's tasks can run on several nodes at the same time, and two tasks of the same project may run on different nodes.
Once a task has a slot, it stays on that node: stopping it, or a runner that crashed, brings it back to the same slot with its work as it was. If that node is offline, the task waits for it to come back. A task can start over on another node only once its slot is let go:
- its runs fail to start twice on that node within a day; Jaah then tries another of the project's nodes, if it has one;
- it waited on your answer until Jaah stopped it, with nothing unsaved in its slot; your answer starts it in a new slot;
- you reset it, or move it to another project;
- you delete the node;
- Jaah's operators release its slot.
To move a task off an offline node, reset it: that lets its slot go at once.
A task that starts over begins from what it last pushed. Anything it hadn't pushed is lost with its old slot, so let running tasks push or finish before you remove or delete a node.
What limits how many tasks run
Jaah makes a slot for each task as it starts, so slots don't limit how many tasks run: there's no limit per project or per node. How many of your organization's tasks run at once is set by your plan's Agents and by the room on your model accounts. A task waits as Queued while it can't start, for example when none of its project's nodes takes new tasks. Another node spreads a project's work and lets new tasks start when one node is offline. An epic's subtasks each take a slot too. See How epics and features work.
Who can do what
Changing a project's slots and nodes needs the org admin role. Seeing who holds a node's slots needs the permission to view worktrees. See How team and access work.