[{"data":1,"prerenderedAt":32},["ShallowReactive",2],{"$f1isbm0p2k84gu":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\u002Fexecutions","Executions","The connected runs of more than one task: one piece of work as it moves from member to member.",null,false,[],"\u003Ch2 id=\"what-an-execution-is\">What an execution is\u003C\u002Fh2>\n\u003Cp>A \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fruns\">run\u003C\u002Fa> is one pass of one task. When a task hands its result to another task, and that one to\nthe next, those runs are one \u003Cstrong>execution\u003C\u002Fstrong>: the whole piece of work, however many members and teams it crosses.\u003C\u002Fp>\n\u003Cp>Runs join an execution only through an explicit link: a handoff to a successor, a retry, a recovery, or a resume.\nTwo runs about the same issue, or at the same time, are not joined unless one led to the other. A run on its own, or\na task retrying itself without ever handing off, is a run and not an execution: it is on \u003Cstrong>Runs\u003C\u002Fstrong>, not\n\u003Cstrong>Executions\u003C\u002Fstrong>.\u003C\u002Fp>\n\u003Cp>An execution keeps one address for good: the run it started at. Any of its runs' addresses also opens it.\u003C\u002Fp>\n\u003Ch2 id=\"the-board\">The board\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Executions\u003C\u002Fstrong> in the portal is a board of five lanes, which you can search and filter by team or member:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Lane\u003C\u002Fth>\n\u003Cth>What is in it\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Backlog\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Items on a team's work list that no run has claimed yet, in the list's order, and a parent whose children are all still there. An item still waiting for a person's approval says so.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Ready\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Queued, about to start.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>In Progress\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Running now.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Blocked\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Waiting on you (a gate), or paused because a spend cap was reached; or one of its runs is on \u003Cstrong>Blockers\u003C\u002Fstrong>, as a failure nobody has cleared, a blocked run, or a pipeline that stopped; or its work is on \u003Cstrong>Waiting\u003C\u002Fstrong>: its last run ended without finishing the work, and nothing has picked it up. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs#finished-work\">Finished work\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Complete\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Everything else. Its status still says how it ended: succeeded, failed, cancelled, skipped, or stopped.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>An item with no parent is one card for its whole life. It sits in \u003Cstrong>Backlog\u003C\u002Fstrong> until a run claims it. From then on\nit is part of that run's execution card, which moves through the lanes as the execution does; while the run is on\nno execution yet, the item's own card stands in the run's lane. A parent card follows its children. It is in\n\u003Cstrong>In Progress\u003C\u002Fstrong> when any child is still in progress, even if another child has already finished, and even if that\nchild's run has ended without closing the item. Otherwise it is in \u003Cstrong>Blocked\u003C\u002Fstrong>, otherwise \u003Cstrong>Ready\u003C\u002Fstrong> when one is\nqueued, otherwise \u003Cstrong>Backlog\u003C\u002Fstrong>. It is in \u003Cstrong>Complete\u003C\u002Fstrong> only when every child has finished and the parent itself is\nclosed; an open parent whose children have all finished stays where its own state puts it. The children are inside\nthat card, each with its own state and the run holding it, and a child does not also have a card of its own. The\nparent's stored state is unchanged, and opening the card still counts the children per lane. Once the work is\nclosed, the card is in \u003Cstrong>Complete\u003C\u002Fstrong>, and opening it shows the item and its history. An item closed without ever\nbeing worked leaves the board; its page and history stay. See the \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbuilt-in\u002Fos\">built-in tools\u003C\u002Fa> for\nhow a task adds, claims and closes items.\u003C\u002Fp>\n\u003Cp>An item's own state always has the last word on its lane. A closed item is never in \u003Cstrong>Blocked\u003C\u002Fstrong>, even when the run\nthat held it is still on \u003Cstrong>Blockers\u003C\u002Fstrong>: it stands on its own in \u003Cstrong>Complete\u003C\u002Fstrong>, and the execution stays in Blocked\nwithout it. An open item is never in \u003Cstrong>Complete\u003C\u002Fstrong>, even when its run has ended: a held item, which waits on someone\nto release it, is in \u003Cstrong>Blocked\u003C\u002Fstrong>, one in progress is in \u003Cstrong>In Progress\u003C\u002Fstrong>, and any other is in \u003Cstrong>Backlog\u003C\u002Fstrong>. An execution\nheld in Blocked only because its work is on \u003Cstrong>Waiting\u003C\u002Fstrong> moves to \u003Cstrong>Complete\u003C\u002Fstrong> once every item it holds is closed, and\n\u003Cstrong>Close completed\u003C\u002Fstrong> closes it with the rest.\u003C\u002Fp>\n\u003Cp>You shape the list from a card or from the item's page: approve or decline an item a task proposed (declining asks\nfor a reason, which the proposing task can read on the item), move it to the top, up, down or to the bottom, put it\non hold and release it, and drop it. A held item is skipped by every run until it is released, and the item moved to\nthe top is the next one a run claims. An item is also held when the pipeline working it stops short (a run failed,\nwas blocked, hit a loop cap or ended on an outcome with nowhere to go): its card names the run and says the pipeline\nstopped. \u003Cstrong>Retry\u003C\u002Fstrong> on Blockers carries the item on, and \u003Cstrong>Clear\u003C\u002Fstrong> or \u003Cstrong>Cancel\u003C\u002Fstrong> there puts it back on the list, so a\nstopped pipeline is never picked up again in the same place by itself. \u003Cstrong>Add work item\u003C\u002Fstrong> on the board adds one to a team's list, and \u003Cstrong>Approve all\u003C\u002Fstrong>\non the Backlog lane approves every proposed item shown in one step. Each action is kept in the item's history with\nthe person who took it. Only a person approves a proposed item or releases a held one: a task cannot, so no run\nclaims an item a task proposed until you have approved it.\u003C\u002Fp>\n\u003Ch3 id=\"grouped\">Grouped\u003C\u002Fh3>\n\u003Cp>\u003Cstrong>Grouped\u003C\u002Fstrong>, beside \u003Cstrong>Board\u003C\u002Fstrong>, shows the work lists instead of the lanes: every open item of each team in view (or\nof the team you filter to), nested under its parent, such as a campaign or an epic. An item names one parent on the\nsame team, one level deep, when it is added (the \u003Cstrong>Parent\u003C\u002Fstrong> field of \u003Cstrong>Add work item\u003C\u002Fstrong>, a task's\n\u003Ccode>os.add_work_item\u003C\u002Fcode>, the API or MCP) or later through \u003Ccode>os.update_work_item\u003C\u002Fcode>, the API or MCP; an item with no parent\nstands at the top level. Each parent starts collapsed and shows how many items sit under it and a count of them per\nstate, closed ones included, so the count moves as a child closes. Every row shows the item's state and the status\nof the run holding it. \u003Cstrong>In progress\u003C\u002Fstrong> shows only the items being worked, with the parents that have one opened and\nonly those children under them; a parent that is itself in progress with none of its children moving is listed\ncollapsed. The search field narrows the titles the same way. Turning the filter off brings back the parents you had\nopened. A child whose parent is closed still shows under it, with the parent marked closed. \u003Cstrong>Board\u003C\u002Fstrong> stays the\nview the page opens on.\u003C\u002Fp>\n\u003Cp>An execution that crosses several teams appears on each of those teams' boards. A failed attempt that a retry then\ncompletes does not make the execution fail; a failed or missing handoff stays visible even when another branch\nfinishes. The board and each execution's page update every few seconds while you are looking at them.\u003C\u002Fp>\n\u003Ch2 id=\"one-execution\">One execution\u003C\u002Fh2>\n\u003Cp>An execution's page shows the task graph it moved through (every successor the tasks are set to hand to, and which\nones it took), the run history with each run's member and team, and the current task. Select a task to see its\nattempts and open any run. Runs' own logs, gates and actions stay on the run's page.\u003C\u002Fp>\n\u003Cp>A task can give its execution a name and attach links (the issue, the pull request, the preview) while it runs;\nthey show on the execution and on its runs. Until one does, an execution is named after its first task.\u003C\u002Fp>\n\u003Ch2 id=\"cancelling-and-closing\">Cancelling and closing\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Cancel\u003C\u002Fstrong> stops every open run in the execution.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Close\u003C\u002Fstrong> takes a finished execution off the board, so the board shows current work. Only an execution in the\nComplete lane can be closed: anything queued, running, waiting or still on Blockers cannot, so a close never hides\nwork that needs someone. Closing records who and when, changes nothing about the runs, and can be undone with\n\u003Cstrong>Reopen\u003C\u002Fstrong>. If new work joins a closed execution (a retry, a new handoff), it comes back on the board.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Close completed\u003C\u002Fstrong> closes every execution in the Complete lane under the current search and team filter, after\nconfirming how many.\u003C\u002Fp>\n\u003Ch2 id=\"over-the-api\">Over the API\u003C\u002Fh2>\n\u003Cp>With an \u003Ca href=\"\u002Fdocs\u002Fapi\u002Fauthentication\">API token\u003C\u002Fa> scoped \u003Ccode>executions:read\u003C\u002Fcode> (and \u003Ccode>executions:write\u003C\u002Fcode> to change them):\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Call\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Fexecutions\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The executions, as a paginated list. Closed ones only with \u003Ccode>closed=true\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Fexecutions\u002Fboard\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Every lane in one read, with the same search, team and member filters. \u003Ccode>items\u003C\u002Fcode> holds the work items by lane: an item with no parent on its own, a parent with its children in In Progress when any child is still in progress, otherwise Blocked, Ready or Backlog, and in Complete only when every child has finished and it is closed. A closed item is never in Blocked and an open one never in Complete. Each execution lists the items it holds under \u003Ccode>workItems\u003C\u002Fcode>, except a child that is shown inside its parent.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Fwork-items\u002F{id}\u003C\u002Fcode>, \u003Ccode>…\u002Fhistory\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>One work item, and every change to it, oldest first (\u003Ccode>teams:read\u003C\u002Fcode>).\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Fexecutions\u002F{id}\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>One execution: its runs, links and task graph. Any of its run ids works.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Fexecutions\u002F{id}\u002Fcancel\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Stop every open run in it.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Fexecutions\u002F{id}\u002Fclose\u003C\u002Fcode>, \u003Ccode>…\u002Freopen\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Take a finished execution off the board, or put it back. A refused close is a \u003Ccode>409\u003C\u002Fcode> that says why.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Fexecutions\u002Fclose-completed\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Close every execution in the Complete lane under the given filters.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Fexecutions\u002Fcounts\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>How many executions and runs are running, queued, waiting (and of those, waiting on a gate) and blocked.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>Responses leave out run inputs, logs and results; read those on the run.\u003C\u002Fp>\n",[12,16,19,23,26,29],{"id":13,"text":14,"level":15,"planned":8},"what-an-execution-is","What an execution is",2,{"id":17,"text":18,"level":15,"planned":8},"the-board","The board",{"id":20,"text":21,"level":22,"planned":8},"grouped","Grouped",3,{"id":24,"text":25,"level":15,"planned":8},"one-execution","One execution",{"id":27,"text":28,"level":15,"planned":8},"cancelling-and-closing","Cancelling and closing",{"id":30,"text":31,"level":15,"planned":8},"over-the-api","Over the API",1794928143960]