[{"data":1,"prerenderedAt":38},["ShallowReactive",2],{"$f14zg2ihrv5vhp":3},{"href":4,"title":5,"description":6,"kind":7,"mark":7,"planned":8,"contributors":9,"provenance":7,"express":8,"bridge":8,"html":10,"headings":11},"\u002Fdocs\u002Fwork\u002Ftool-slots","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.",null,false,[],"\u003Ch2 id=\"why-a-slot\">Why a slot\u003C\u002Fh2>\n\u003Cp>A task normally names its tools by the tool they come from: \u003Ccode>github.create_issue\u003C\u002Fcode>. 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.\u003C\u002Fp>\n\u003Cp>A \u003Cstrong>tool slot\u003C\u002Fstrong> names the kind of tool instead. The task declares a slot, \u003Ccode>codehost\u003C\u002Fcode>, and names its tools by it: \u003Ccode>codehost\u003C\u002Fcode>, or \u003Ccode>codehost.create_issue\u003C\u002Fcode>. 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.\u003C\u002Fp>\n\u003Ch2 id=\"declaring-a-slot-on-a-task\">Declaring a slot on a task\u003C\u002Fh2>\n\u003Cp>A task version lists its slots in \u003Ccode>toolSlots\u003C\u002Fcode>. Each slot has a key, a label, and an optional description:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;toolSlots&quot;: [\n        {\n            &quot;key&quot;: &quot;codehost&quot;,\n            &quot;label&quot;: &quot;Code host&quot;,\n            &quot;description&quot;: &quot;Where the repository, its issues and its pull requests live&quot;\n        }\n    ],\n    &quot;tools&quot;: [&quot;codehost&quot;, &quot;os.set_execution_name&quot;]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cul>\n\u003Cli>The \u003Cstrong>key\u003C\u002Fstrong> reads like a tool type: a lowercase letter, then letters, digits, \u003Ccode>_\u003C\u002Fcode> or \u003Ccode>-\u003C\u002Fcode>, up to 32 characters. It cannot be \u003Ccode>os\u003C\u002Fcode>, \u003Ccode>workspace\u003C\u002Fcode>, \u003Ccode>memory\u003C\u002Fcode> or \u003Ccode>web\u003C\u002Fcode>, which belong to the OS.\u003C\u002Fli>\n\u003Cli>The \u003Cstrong>label\u003C\u002Fstrong> is what a person reads when they choose a connection for the slot, up to 80 characters.\u003C\u002Fli>\n\u003Cli>A task declares at most 16 slots.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>The task's tools, its gates and its workspace credentials may all name a slot. \u003Ccode>codehost\u003C\u002Fcode> 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 (\u003Ccode>tool_slot_unused\u003C\u002Fcode>), because it is almost always a renamed key.\u003C\u002Fp>\n\u003Cp>On the task page, slots are under \u003Cstrong>Tool slots\u003C\u002Fstrong> in the task's settings. Over the API they are part of the version body (see \u003Ca href=\"\u002Fdocs\u002Fapi\u002Ftasks\">Tasks\u003C\u002Fa>).\u003C\u002Fp>\n\u003Ch2 id=\"slot-actions\">Slot actions\u003C\u002Fh2>\n\u003Cp>Two servers of one kind rarely name their tools alike. One code host merges with \u003Ccode>merge_pull_request\u003C\u002Fcode>; another has one \u003Ccode>pull_request_write\u003C\u002Fcode> tool and a \u003Ccode>method\u003C\u002Fcode>. A task that names \u003Ccode>codehost.merge_pull_request\u003C\u002Fcode> therefore runs only where a server with a tool of that name fills the slot.\u003C\u002Fp>\n\u003Cp>A slot can instead declare the \u003Cstrong>actions\u003C\u002Fstrong> the task needs, and the task names those:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;toolSlots&quot;: [\n        {\n            &quot;key&quot;: &quot;codehost&quot;,\n            &quot;label&quot;: &quot;Code host&quot;,\n            &quot;actions&quot;: [\n                { &quot;name&quot;: &quot;pr.create&quot;, &quot;description&quot;: &quot;open a pull request&quot; },\n                { &quot;name&quot;: &quot;pr.merge&quot;, &quot;description&quot;: &quot;merge a pull request&quot; }\n            ]\n        }\n    ],\n    &quot;tools&quot;: [&quot;codehost.pr.create&quot;, &quot;codehost.pr.merge&quot;, &quot;os.set_execution_name&quot;],\n    &quot;gates&quot;: [{ &quot;tool&quot;: &quot;codehost.pr.merge&quot;, &quot;owner&quot;: &quot;ceo&quot;, &quot;approval&quot;: &quot;specific&quot; }]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cul>\n\u003Cli>An action name is lowercase words joined by dots (\u003Ccode>pr.merge\u003C\u002Fcode>), at most 32 per slot, each with an optional description of up to 200 characters for the person mapping it.\u003C\u002Fli>\n\u003Cli>The task names no vendor's tool. A name under the key that is not a declared action (\u003Ccode>codehost.list_branches\u003C\u002Fcode>) is still one server's own tool name, so a save warns about it (\u003Ccode>tool_slot_action_undeclared\u003C\u002Fcode>).\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>Each connection that fills the slot carries an \u003Cstrong>action map\u003C\u002Fstrong>: 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:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{ &quot;pr.create&quot;: &quot;pull_request_write#method=create&quot;, &quot;pr.merge&quot;: &quot;pull_request_write#method=merge&quot; }\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>and for one with a tool per action, \u003Ccode>{ &quot;pr.create&quot;: &quot;create_pull_request&quot;, &quot;pr.merge&quot;: &quot;merge_pull_request&quot; }\u003C\u002Fcode>. A connection made from the Tools directory starts with the map its vendor's entry holds. Whoever may edit the connection may change it:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>On Tools.\u003C\u002Fstrong> Edit a connection that fills the slot and its \u003Cstrong>Actions\u003C\u002Fstrong> section sits beside \u003Cstrong>Fills slots\u003C\u002Fstrong>: 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 (\u003Ccode>method=merge\u003C\u002Fcode>) 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 \u003Cstrong>Action map\u003C\u002Fstrong> text box instead: one \u003Ccode>action=tool\u003C\u002Fcode> a line, such as \u003Ccode>pr.merge=pull_request_write#method=merge\u003C\u002Fcode>, where a line you remove clears that action.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Over the API.\u003C\u002Fstrong> Send \u003Ccode>slotActions\u003C\u002Fcode> on \u003Ccode>PATCH \u002Fv1\u002Ftools\u002Fbindings\u002F:id\u003C\u002Fcode> as a whole map. A blank value clears that one action.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>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.\u003C\u002Fp>\n\u003Cp>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, \u003Ccode>codehost.pr.merge\u003C\u002Fcode> needs the gate \u003Ccode>pull_request_write\u003C\u002Fcode> narrowed to \u003Ccode>method: merge\u003C\u002Fcode> would. Two actions the map puts on one tool (\u003Ccode>pr.create\u003C\u002Fcode> and \u003Ccode>pr.merge\u003C\u002Fcode> above) are served as that one tool pinned to both values, and a pin becomes a gate's \u003Ccode>match\u003C\u002Fcode>, so the gate on \u003Ccode>codehost.pr.merge\u003C\u002Fcode> waits on \u003Ccode>pull_request_write\u003C\u002Fcode> calls whose \u003Ccode>method\u003C\u002Fcode> is \u003Ccode>merge\u003C\u002Fcode> and on nothing else. A run whose filling connection does not map an action the task names stops before it starts, \u003Ccode>tool_action_unmapped:codehost.pr.merge\u003C\u002Fcode>, and resumes by itself once the map names it. It isn't a credential problem: the connection's token is fine. \u003Cstrong>Blockers\u003C\u002Fstrong> says which slot's connection lacks which actions, and its \u003Cstrong>Map it\u003C\u002Fstrong> opens that connection's \u003Cstrong>Actions\u003C\u002Fstrong> on \u003Cstrong>Tools\u003C\u002Fstrong> (or \u003Cstrong>Tools\u003C\u002Fstrong> itself when no connection can be named). It lists the run's block class as \u003Ccode>action_map\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>In the catalog review, \u003Cstrong>Slots to fill\u003C\u002Fstrong> 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.\u003C\u002Fp>\n\u003Ch3 id=\"missing-actions\">Missing actions\u003C\u002Fh3>\n\u003Cp>You don't have to wait for a run to stop to see a gap. Each connection's card on \u003Cstrong>Tools\u003C\u002Fstrong>, 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 \u003Ccode>missingSlotActions\u003C\u002Fcode> field (\u003Ccode>GET \u002Fv1\u002Ftools\u002Fbindings\u003C\u002Fcode>, and the row a connect or an edit returns).\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>What counts.\u003C\u002Fstrong> The actions its tasks name under a slot it fills (a key in \u003Cstrong>Fills slots\u003C\u002Fstrong>, 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 \u003Ccode>tool_action_unmapped\u003C\u002Fcode>. An action only the directory entry maps, and no task names, is not missing.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Which tasks.\u003C\u002Fstrong> 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.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Always an object.\u003C\u002Fstrong> The field is always present. \u003Ccode>{}\u003C\u002Fcode> means nothing is missing, and it is never \u003Ccode>null\u003C\u002Fcode>.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>The value.\u003C\u002Fstrong> 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 (\u003Ccode>''\u003C\u002Fcode>) otherwise: there's no known tool, so map it by hand under \u003Cstrong>Actions\u003C\u002Fstrong>.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>When at least one missing action has a tool, \u003Cstrong>Add missing actions\u003C\u002Fstrong> writes those in one save, on any connection, whether it lists slots under \u003Cstrong>Fills slots\u003C\u002Fstrong> 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 \u003Cstrong>Edit\u003C\u002Fstrong> 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.\u003C\u002Fp>\n\u003Ch2 id=\"filling-a-slot\">Filling a slot\u003C\u002Fh2>\n\u003Cp>A connection fills a slot when its \u003Cstrong>Fills slots\u003C\u002Fstrong> list on \u003Cstrong>Tools\u003C\u002Fstrong> names the key. Anyone who may edit the connection may set it, Express connections included. Over the API it is the binding's \u003Ccode>slots\u003C\u002Fcode> list (\u003Ccode>PATCH \u002Fv1\u002Ftools\u002Fbindings\u002F:id\u003C\u002Fcode>).\u003C\u002Fp>\n\u003Cp>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 \u003Ccode>github\u003C\u002Fcode> that fills \u003Ccode>codehost\u003C\u002Fcode> serves \u003Ccode>codehost.create_issue\u003C\u002Fcode> as \u003Ccode>github.create_issue\u003C\u002Fcode>, with its own credential.\u003C\u002Fp>\n\u003Cp>Three rules decide the edge cases:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>A connection named for the key wins.\u003C\u002Fstrong> If the company has a connection whose tool type is the key itself (\u003Ccode>codehost\u003C\u002Fcode>), that connection is used directly, as it was before slots existed.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Several hosts at one level.\u003C\u002Fstrong> When two connections of different tools fill the same slot at the same level, the one whose \u003Ccode>git.repos\u003C\u002Fcode> custom prop lists the run's repository is used. \u003Ccode>git.repos\u003C\u002Fcode> takes \u003Ccode>owner\u002Fname\u003C\u002Fcode> entries, or \u003Ccode>owner\u002F*\u003C\u002Fcode> for every repository of an owner, comma separated. A connection with no \u003Ccode>git.repos\u003C\u002Fcode> fills the slot for any repository. If that still leaves two, the run stops with \u003Ccode>tool_slot_ambiguous:&lt;key&gt;\u003C\u002Fcode> until you add \u003Ccode>git.repos\u003C\u002Fcode> or remove one.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Nothing fills it.\u003C\u002Fstrong> A run whose slot nothing fills stops before it starts, with \u003Ccode>tool_not_bound:&lt;key&gt;\u003C\u002Fcode>, the same as a tool nobody connected. Filling the slot resumes it by itself.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"the-missing-binding-notice\">The missing-binding notice\u003C\u002Fh2>\n\u003Cp>When a run stops because a tool it needs is not connected for the member running it, the company owner gets a \u003Cstrong>missing-binding notice\u003C\u002Fstrong> in \u003Cstrong>Needs you\u003C\u002Fstrong>, under \u003Cstrong>Members who can't start work yet\u003C\u002Fstrong> and titled \u003Cstrong>A tool isn't connected\u003C\u002Fstrong>, and in the next Needs you email. It names the member and the tool (Gitea, and what the tasks do with it, such as &quot;issue read&quot;; Advanced mode adds the exact tool names), and its \u003Cstrong>Connect\u003C\u002Fstrong> button opens the \u003Cstrong>Tools page\u003C\u002Fstrong> 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.\u003C\u002Fp>\n\u003Cp>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.\u003C\u002Fp>\n\u003Ch2 id=\"approvals-still-apply\">Approvals still apply\u003C\u002Fh2>\n\u003Cp>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. \u003Ccode>codehost.merge_pull_request\u003C\u002Fcode> needs the same gate as \u003Ccode>github.merge_pull_request\u003C\u002Fcode> when the \u003Ccode>github\u003C\u002Fcode> connection fills \u003Ccode>codehost\u003C\u002Fcode>. A gate a task declares on a slot's tool (\u003Ccode>codehost.merge_pull_request\u003C\u002Fcode>) covers the call whichever connection fills the slot.\u003C\u002Fp>\n\u003Ch2 id=\"sharing-a-team-that-uses-slots\">Sharing a team that uses slots\u003C\u002Fh2>\n\u003Cp>When you clone a team or a role from the catalog, the review lists each slot its tasks declare, under \u003Cstrong>Slots to fill\u003C\u002Fstrong>. 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.\u003C\u002Fp>\n\u003Cp>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 \u003Ca href=\"#slot-actions\">slot actions\u003C\u002Fa> its gates carry over exactly.\u003C\u002Fp>\n",[12,16,19,22,26,29,32,35],{"id":13,"text":14,"level":15,"planned":8},"why-a-slot","Why a slot",2,{"id":17,"text":18,"level":15,"planned":8},"declaring-a-slot-on-a-task","Declaring a slot on a task",{"id":20,"text":21,"level":15,"planned":8},"slot-actions","Slot actions",{"id":23,"text":24,"level":25,"planned":8},"missing-actions","Missing actions",3,{"id":27,"text":28,"level":15,"planned":8},"filling-a-slot","Filling a slot",{"id":30,"text":31,"level":15,"planned":8},"the-missing-binding-notice","The missing-binding notice",{"id":33,"text":34,"level":15,"planned":8},"approvals-still-apply","Approvals still apply",{"id":36,"text":37,"level":15,"planned":8},"sharing-a-team-that-uses-slots","Sharing a team that uses slots",1794928144025]