Tool slots
Name a task's tools by a slot, such as a code host, and let each company fill it with the tool it connected, so one task works with any vendor.
Why a slot
A task normally names its tools by the tool they come from: github.create_issue. That task only works for a company that connected GitHub under that name. A team shared through the catalog then breaks for a company whose code lives somewhere else.
A tool slot names the kind of tool instead. The task declares a slot, codehost, and names its tools by it: codehost, or codehost.create_issue. Each company says which of its own connections fills the slot. The same task then runs against GitHub for one company and GitLab or Gitea for another, with no change to the task.
Declaring a slot on a task
A task version lists its slots in toolSlots. Each slot has a key, a label, and an optional description:
{
"toolSlots": [
{
"key": "codehost",
"label": "Code host",
"description": "Where the repository, its issues and its pull requests live"
}
],
"tools": ["codehost", "os.set_execution_name"]
}
- The key reads like a tool type: a lowercase letter, then letters, digits,
_or-, up to 32 characters. It cannot beos,workspace,memoryorweb, which belong to the OS. - The label is what a person reads when they choose a connection for the slot, up to 80 characters.
- A task declares at most 16 slots.
The task's tools, its gates and its workspace credentials may all name a slot. codehost alone is the filling tool's whole catalogue, as a bare tool type is. A slot that no tool or gate names is flagged on save (tool_slot_unused), because it is almost always a renamed key.
On the task page, slots are under Tool slots in the task's settings. Over the API they are part of the version body (see Tasks).
Slot actions
Two servers of one kind rarely name their tools alike. One code host merges with merge_pull_request; another has one pull_request_write tool and a method. A task that names codehost.merge_pull_request therefore runs only where a server with a tool of that name fills the slot.
A slot can instead declare the actions the task needs, and the task names those:
{
"toolSlots": [
{
"key": "codehost",
"label": "Code host",
"actions": [
{ "name": "pr.create", "description": "open a pull request" },
{ "name": "pr.merge", "description": "merge a pull request" }
]
}
],
"tools": ["codehost.pr.create", "codehost.pr.merge", "os.set_execution_name"],
"gates": [{ "tool": "codehost.pr.merge", "owner": "ceo", "approval": "specific" }]
}
- An action name is lowercase words joined by dots (
pr.merge), at most 32 per slot, each with an optional description of up to 200 characters for the person mapping it. - The task names no vendor's tool. A name under the key that is not a declared action (
codehost.list_branches) is still one server's own tool name, so a save warns about it (tool_slot_action_undeclared).
Each connection that fills the slot carries an action map: which of its own tools each action is, pinned where one tool does several things. For a code host whose one pull-request tool both opens and merges:
{ "pr.create": "pull_request_write#method=create", "pr.merge": "pull_request_write#method=merge" }
and for one with a tool per action, { "pr.create": "create_pull_request", "pr.merge": "merge_pull_request" }. A connection made from the Tools directory starts with the map its vendor's entry holds. Whoever may edit the connection may change it:
- On Tools. Edit a connection that fills the slot and its Actions section sits beside Fills slots: a row for each action the slot's tasks declare, with its description, a row for each other action its map already names, and a free row for one more. On each row, pick the tool from the list the connection's server serves, or type the tool's name when that list can't be read, and fill in the optional second box (
method=merge) only when one tool does several things. Saving sends the whole map, so a row you clear clears that action. When you add a connection, or edit one that fills no slot, you get the Action map text box instead: oneaction=toola line, such aspr.merge=pull_request_write#method=merge, where a line you remove clears that action. - Over the API. Send
slotActionsonPATCH /v1/tools/bindings/:idas a whole map. A blank value clears that one action.
When the directory updates a vendor's map, the update reaches every connection made through that entry on the vendor's own server, with nobody at your company doing anything. Each action the connection doesn't map yet is added. An action it already maps keeps the tool you gave it. The same goes for the entry's toolsets, on a connection whose toolsets were never set.
When a run starts, each action is replaced by the filling connection's tool for it, so the model is served that server's real tool, a gate on the action waits on exactly that call, and the connection's must-gate list holds the action as it holds the tool: with the map above, codehost.pr.merge needs the gate pull_request_write narrowed to method: merge would. Two actions the map puts on one tool (pr.create and pr.merge above) are served as that one tool pinned to both values, and a pin becomes a gate's match, so the gate on codehost.pr.merge waits on pull_request_write calls whose method is merge and on nothing else. A run whose filling connection does not map an action the task names stops before it starts, tool_action_unmapped:codehost.pr.merge, and resumes by itself once the map names it. It isn't a credential problem: the connection's token is fine. Blockers says which slot's connection lacks which actions, and its Map it opens that connection's Actions on Tools (or Tools itself when no connection can be named). It lists the run's block class as action_map.
In the catalog review, Slots to fill lists each slot's actions and, for every connection you could fill it with, the ones its map does not name yet. So a team can be adopted on a code host its publisher never used: connect it, map the actions once, fill the slot.
Missing actions
You don't have to wait for a run to stop to see a gap. Each connection's card on Tools, and each of a team's connections on its team screen, shows how many actions it is missing and which ones, the moment it is listed. Over the API it is the connection's missingSlotActions field (GET /v1/tools/bindings, and the row a connect or an edit returns).
- What counts. The actions its tasks name under a slot it fills (a key in Fills slots, or its own tool type when that is the key) that its map holds no tool for. The run checks the same thing when it starts, so an action listed here is one a run would stop on with
tool_action_unmapped. An action only the directory entry maps, and no task names, is not missing. - Which tasks. The current version of each task a run through it could be, never a draft: on a task, that task; on a team, that team's tasks; company-wide, on a member or on a role, every task of your company.
- Always an object. The field is always present.
{}means nothing is missing, and it is nevernull. - The value. Each missing action maps to the tool its directory entry gives it when the connection is on that entry's own server, and to an empty string (
'') otherwise: there's no known tool, so map it by hand under Actions.
When at least one missing action has a tool, Add missing actions writes those in one save, on any connection, whether it lists slots under Fills slots or is used under its own tool type. It writes only the ones with a tool and never changes an action the connection already maps, and the card then says how many it added. For the rest, the card tells you to choose Edit and pick the tool the connection should use for each one. In Advanced mode the card also shows the tool each missing action would be given.
Filling a slot
A connection fills a slot when its Fills slots list on Tools names the key. Anyone who may edit the connection may set it, Express connections included. Over the API it is the binding's slots list (PATCH /v1/tools/bindings/:id).
When a run starts, each slot its task declares is filled by the nearest connection that fills it, in the usual order: the task, its role, the member, the team, then the company. The run then names those tools by the filling connection's own tool type. A connection called github that fills codehost serves codehost.create_issue as github.create_issue, with its own credential.
Three rules decide the edge cases:
- A connection named for the key wins. If the company has a connection whose tool type is the key itself (
codehost), that connection is used directly, as it was before slots existed. - Several hosts at one level. When two connections of different tools fill the same slot at the same level, the one whose
git.reposcustom prop lists the run's repository is used.git.repostakesowner/nameentries, orowner/*for every repository of an owner, comma separated. A connection with nogit.reposfills the slot for any repository. If that still leaves two, the run stops withtool_slot_ambiguous:<key>until you addgit.reposor remove one. - Nothing fills it. A run whose slot nothing fills stops before it starts, with
tool_not_bound:<key>, the same as a tool nobody connected. Filling the slot resumes it by itself.
The missing-binding notice
When a run stops because a tool it needs is not connected for the member running it, the company owner gets a missing-binding notice in Needs you, under Members who can't start work yet and titled A tool isn't connected, and in the next Needs you email. It names the member and the tool (Gitea, and what the tasks do with it, such as "issue read"; Advanced mode adds the exact tool names), and its Connect button opens the Tools page with the form set to connect that tool for that member. All of one member's refusals for the same tool fold into one notice, so a new member who is missing Gitea gets one notice, not one per run.
To clear it, connect the tool for that member on the Tools page, or connect it for their role, their team or the whole company. The waiting runs then start by themselves and the notice goes away. A member's page also lists, before any run needs it, each tool their roles' tasks need that none of their connections reaches.
Approvals still apply
A slot never takes a tool out of an approval. A connection's must-gate list (the tools a task may only call with a gate, such as a merge) also holds for every slot the connection fills. codehost.merge_pull_request needs the same gate as github.merge_pull_request when the github connection fills codehost. A gate a task declares on a slot's tool (codehost.merge_pull_request) covers the call whichever connection fills the slot.
Sharing a team that uses slots
When you clone a team or a role from the catalog, the review lists each slot its tasks declare, under Slots to fill. You choose one of your connections for each. The connection is told it fills the slot, and the tasks are installed exactly as published, so they stay linked to the template and keep receiving its updates. A slot that one of your connections already fills is shown as filled.
This is the difference from swapping a tool. A swap rewrites the task to name another vendor and makes it your own copy, and every call to the replacement waits on your approval, because the template's gates were written for the tool it replaced. A slot needs no rewrite, because the task never named a vendor, and with slot actions its gates carry over exactly.