The web interface

workflow --web serves the same loop in a browser: the same issues, branch, pull request and announcement the terminal interface shows, read from the same repository and services through the same code. It is another way in, not a second implementation, and the terminal stays the fuller of the two.

Start it

workflow --web              # serve http://127.0.0.1:13579
workflow --web --dry-run    # the same, read-only
workflow --web --port 7001  # serve http://127.0.0.1:7001

Run it inside a repository, then open the address it prints on stderr, which looks like http://127.0.0.1:13579/#session=…. It listens on the loopback interface alone, on port 13579 unless --port names another (1 to 65535; --port goes only with --web), and refuses a write from a page served anywhere else, so a site open in another tab cannot drive it; nor can a site show the page inside one of its own. ctrl+c in the terminal stops it. Closing or reloading a page stops what the server was still reading for that page alone; a change the page asked for goes on to its end, unless ctrl+c stops the server first.

The session. Each run makes a session as it starts, and only a request that presents it is answered, so another program or another account on the machine cannot drive the server just by reaching the loopback address. The address it prints carries the session after #session=, in the part a browser never sends to a server: the page keeps it in this browser for that address, takes it out of the address bar, and presents it on every request. A tab opened later at the same address uses the one kept. A page opened without it, or after the server was started again, says to open the address the running server printed. Treat that address as you would a password while the server runs; it is no use once the run ends. With no .workflow.json to read, it says so on stderr and serves anyway: Settings sets a first one up (see Setting up), as workflow config init does at a prompt.

Every build carries the web app inside it: the release binaries, task build and go install alike.

Read-only with --dry-run. A banner under the header says so, and every write is held back in the browser before it is sent, saying Held back by –dry-run: nothing was sent. The server refuses every write as well, so nothing changes even if a request gets past the page. Unlike the terminal, the web does not narrate what a held-back write would have done.

The page

The header holds the version, where the server works, the theme and the stream’s state. Under it runs the loop: the checked-out branch’s five stages — Issue, Branch, Commits, Review and your messaging service — each with its state’s mark and a rule that fills in its system’s color as the stage gets done; the Review rule fills as CI’s checks finish. A stage not yet begun is faint, and a failed one red. The Taskwarrior task you have started, when there is one, ends the loop’s row, or takes a row of its own on a narrow window. The rail down the left holds the nine sections; the one you are in, and its heading, take the hue of the system it belongs to. Below a medium width the rail keeps its icons alone; each still has its name, shown on hover and read by a screen reader.

The theme button cycles System, Light and Dark. System follows your operating system; the choice is remembered in this browser.

The type is Recursive, one variable face the binary carries and serves itself, so the page fetches nothing from elsewhere: proportional for what you read, and at its monospaced setting for what you would type into a terminal — a branch, a commit, a path. It covers the Latin alphabets; text in another script draws in your system’s own face beside it. Its SIL Open Font License is served beside it, at /fonts/Recursive-OFL.txt.

The stream keeps the page current. Every five seconds, and at once after anything you do here, the server pushes each open tab what it finds, so nothing on the page needs refreshing by hand. What you do says it is done only once a push read after it is on the page, so its word comes with a page that shows it done: the server numbers what you do, and each push counts what it was read after, so a push already going out at that instant, or one that arrived first, is told apart from the one that shows it. Each push reads the repository afresh — the branch, the working tree, the branches and worktrees, the commit scope — and Taskwarrior, all on this machine. What it asks over the network is shared by every tab: the issue search is made at most once every timing.ci_interval (twenty seconds unless set) for each view, and again on the next push after a status change or an assignment made here, and each search’s first page is kept in the store for the next session, as the terminal keeps it (never under --dry-run); which of the branches' issues are yours, once a minute, and again after an assignment made here; the forge — the pull request, its reviews and its CI — at most once every timing.ci_interval, and at once when another branch is checked out or its head commit moves, while a pull request the page opens shows from the open on, without asking the forge, and until the forge’s list of the branch’s pull requests includes it, each read asks for it by its number; and who the forge says you are, until it answers, at most once every timing.ci_interval. A tab that has an answer to show is not held up by another tab’s read of the forge or the tracker, except after an edit, a merge, a finish or a re-run of the pull request, a status change (a move to review among them), or an assignment, made here: the next push waits for the read that follows it, so it shows what changed. A forge read that fails keeps the last answer for the same branch and head commit, and says why beside it. A read that fails shows as a failure in its section, with the reason, rather than as an empty one: the Issues list does not say no issue matches, the Branch section does not say the directory is no repository, and the Review section does not offer to open a pull request, while Jira, git or the forge cannot be read. A service that is not set up — no Jira or forge token, a base remote that names no forge — is no failure: the section says, in the muted color beside the not-started mark, that it is not set up and how to set it up, in place of what it would have shown. When the store holds the view’s issues from an earlier read — the terminal’s or this page’s — the server sends them first, read from disk before anything is asked of the network, so Issues lists them at once while every other section waits for the first update; --dry-run neither reads nor keeps them. The stream’s state is beside the theme, and a section waiting on its first update says the same word:

  • Connecting — the page has not had its first update yet.
  • Live — updates are arriving.
  • Reconnecting — the connection dropped; the browser is finding its way back, and the page shows the last update until it does.
  • Out of date — updates arrive but this page cannot read them, which happens when the server is a newer or older build than the page. Reload the page. Why is shown on hover and read by a screen reader.
  • Disconnected — what answered at the page’s address was not workflow’s stream, so the browser gave it up: another program on the port, or a server that failed before it could answer. Reload the page once workflow is running there.

The forge’s own words. On GitLab the page says merge request and numbers one !12; on GitHub, pull request and #12 — as the terminal does.

The keyboard. Beyond Tab, the page answers the terminal’s own keys, read from its bindings with ui.keys applied, so a key you moved in the file moves here too. ? opens a sheet of the actions the page has a control for, under the terminal’s groups, one for each of its panes (its Commits pane’s keys, which work on Branch here, keep a heading of their own), and in its words, with the key for each; Escape closes it. Ctrl+K, or ⌘K on a Mac, opens a palette of what the section you are in can do (in a Mac’s text field Ctrl+K stays the field’s own key), and of the other sections: type part of an action’s name, choose with the arrow keys, and Enter runs it through its own button, so a push or a merge still asks first. Single keys — c comments, a stages everything on Branch, 2 opens Branch — are off until you turn on Single-key shortcuts in Settings (ui.web_shortcuts), since a key that acts on its own surprises a screen reader or speech user; ? and the palette work either way. Even with them on, a key types into the field that has the focus, a search box or the comment box among them, and acts only outside one; and while a dialog is open — the sheet, the palette, the directory dialog — no key reaches the page behind it. Nor does any key, ? and the palette included, while a confirm, a preview or a form that writes in place — an assignment, a status change, logged work, an amend, a merge — waits on your answer; Settings’ own form holds none. The navigation stays a click away for a deliberate leave. Each control a key reaches says so to assistive technology (aria-keyshortcuts). See Keys on the web.

The sections

Issues

Here the detail is scrolled past PROJ-412’s key, status, title, type, priority, reporter and assignee to its actions and its whole work story; the selected row beside it shows its key, status and title.

The issues in a view — the default is those assigned to you and not done — with a View select for the views your configuration defines, each scoped to your issues unless its query names the assignee, a Search over the issues loaded so far, by key or summary, Filter buttons that narrow them to places, and Load more while the view holds more, which reads on from the last issue loaded, wherever the view has moved it, so an issue joining or leaving the view above it neither skips nor repeats a row. Filter offers the statuses the loaded issues are in, in the workflow’s order as the terminal lists them, and the marks in flight, task active, tracked, task done and forge issue, each with how many issues it holds; pressing one narrows the list, and pressing it again undoes that. Statuses widen each other, as marks do, and the two narrow together, as the terminal’s f does. A repository that lists its forge’s issues beside Jira’s (issues.forge) numbers them as the forge does, #57, links each to its page with Open in GitHub or Open in GitLab, and says so above the list, among its controls, when the forge’s issues could not be read. An issue with a branch is marked in flight, with Switch branch beside it when that branch is not the one checked out — a local branch, or one only the remote has, which checking out creates here. The branches counted are those naming an issue assigned to you and not done, so a branch whose issue was finished or reassigned no longer marks it; while the tracker cannot be asked, its last answer stands, and a branch it has not answered for yet counts until it does. Once Taskwarrior has answered, a row also marks how its issue’s tasks stand: tracked, task active or task done. Until the first update, the list is the one last kept for the view, saying Reading Jira… these are the issues it listed last time., with no row marks and no Load more until Jira answers; a switch of view does the same for the view switched to, its rows marked from the last update.

The selected issue’s detail shows its type, priority, reporter and assignee, a link to open it in Jira, its description and its comments, and its work story: the loop’s stages, titled as the terminal’s top row and workflow status name them — Issue, Branch, Commits, Review, and the messaging service the work is announced on, such as Slack — each opening the section it belongs to. Each step reads done, in flight, not started or failed as the server works it out, by the rules of the terminal’s top row and workflow status. For the issue whose branch is checked out, the issue is done once the branch names it, the commits once there is one, and the review once the pull request’s CI passes or it merges, failed on a CI failure or changes asked for. The announcement is done once the pull request was announced at the moment it is at now — from the browser, the terminal or workflow announce, as the store remembers — but not for one closed without merging, which the loop no longer follows. The server reads the working tree and the forge for the checked-out branch alone, so for an issue on another branch only the issue and the branch read done, and for an issue with no branch yet the issue reads in flight, picked as the terminal’s top row reads an issue selected, and nothing after it begun. From the story, Start work fetches the base remote — upstream in a fork’s clone, else origin — so the branch starts from what it holds now, then creates and checks out a branch named for the issue, and Switch branch switches to one it already has. Start work in a new worktree creates the branch in a new git worktree beside the repository instead, leaving the checkout here as it is, then says where and offers Switch to it. A branch another worktree has checked out, which git will not check out twice, offers Switch to its worktree in place of the checkout. Either asks “Switch to DIR?” first, as every switch in Repositories does, and switches only on Switch there; one held by a worktree whose directory is gone says that git worktree prune frees it. When the fetch fails — the network, the remote’s address, your credential — nothing is made, the reason is said, and Branch from what you have starts the branch from the base as it was last fetched, as the terminal’s branch creator offers. Once Taskwarrior has answered, a Tasks card sits between the story and the description; Tasks says what it holds. Below a large width the list sits over the detail rather than beside it.

Under the people, three buttons change the issue, as the terminal’s t, a and w do. Change status lists every status change the tracker offers from where the issue stands, each by where it leads, named when the change has a name of its own, and saying which fields it needs. Choosing one shows its form: a choice of one value, a box per value for a list such as fix versions, a date, or text or a username. Change to the status sends the change with what was filled, and nothing is sent before that press; a field left empty or given something it does not take is named beside the form, and nothing changes. A change that needs a field only Jira’s own screen can fill, such as a cascading select, says so and cannot be sent from here. A forge issue offers one change, Close. Assign sets the assignee to the username typed, as the issue’s tracker knows it. Log work, on a Jira issue alone, logs a duration in Jira’s words — 2h, 30m, 1d 4h — with an optional note. Each form says what it did once the tracker has it — Changed PROJ-1 to Resolved., Assigned PROJ-1 to ana., Logged 2h on PROJ-1. — and reads the issue again; a refusal stays beside the form, which keeps what was entered. Cancel sends nothing.

The comments are drawn from Jira’s wiki markup: bold, italic, struck and code text, links, headings, quotes, lists and code blocks. Anything else, such as a table, a panel or a color, shows as the text it is, and an image is offered as a link rather than loaded. A link opens in a new tab, and only to an http or https address; one to anywhere else, an email address among them, shows as the text it is. Under the thread, a box takes a comment; on a Jira issue it says it is reading how comments are written until the configuration answers, then draws in that shape. On a Jira issue the comment is Markdown, as jira.markdown_comments is on by default: Write and Preview are tabs, Preview shows it as Jira will, and the buttons beside them write bold, italic, code, a link or a list around what is selected. With it off, the comment is posted as typed, and Jira reads it as wiki markup. Turning it on or off in Settings applies to the next comment, with no restart. Comment posts it and reads the issue again, so the thread shows it as Jira keeps it.

A forge issue, numbered such as #57, takes a comment too. Its thread and its comment are always Markdown, which the forge renders itself, so the box always has Write and Preview, and the comment is posted as written. On GitLab the box also says that a line starting with /, such as /close, runs as a quick action rather than being posted. A comment over 65,536 characters, or with a line over 1,000, is shown as plain text in the thread and in Preview, and so are a thread’s older comments once the newer ones add up to that many.

Branch

The checked-out branch, its base, its upstream and how far it is ahead or behind, and the commits on it; Push to names the remote a push goes to when that is not the base remote, as in a fork’s clone. Push branch publishes it, after a confirmation naming the branch and the remote it goes to; it is not offered on the base branch itself. A branch git could not count against its upstream says it is not counted against it, and is offered the push, since that upstream is not known to hold its commits. Link an issue ties a branch begun outside workflow, whose name names no issue, to one: a Jira key or a forge number such as #42. When its pull request’s description does not name the issue yet, it is shown with the issue’s line added first, with Link and update or Link only. A linked branch says so, with Unlink; the link is kept in the repository’s git configuration, as the terminal’s i keeps it. Rebase onto the base replays the branch onto it, as the terminal’s u does, after a last look that says its commits are rewritten.

Under Working tree, each changed file has its own Stage or Unstage, and Stage all stages the rest; Unstage all beside it takes everything out of the index at once, as the terminal’s U does, leaving the work tree as it is. Discard… on a file asks first, as the terminal’s x does, since it cannot be undone: Discard puts the file back as the last commit has it, staged and unstaged changes alike, and deletes a file the last commit does not have. The commit form builds a Conventional Commit from its type, scope, subject, body and a breaking-change box, with the scope the terminal would suggest already filled in; Commit staged changes commits, adds the trailer naming the branch’s issue (Refs: unless commit.refs_trailer relabels it), and runs the repository’s own hooks. A hook that refuses the commit says why. Show diff under a changed file reads its diff against HEAD, staged and unstaged together, and reads it again when a commit moves HEAD or the file is staged, unstaged or renamed, showing the old diff until the new one comes. An edit to the file’s contents alone does not read it again: Hide diff puts it away, and Show diff reads it afresh.

Under the commits, Run a hook reads the hooks lefthook configures and offers the ones a run by hand can stand in for, as the terminal’s h does, with pre-commit chosen first; it lists the rest, the hooks only git runs, with what git hands each. Run runs the one chosen at once, as git would, without committing or pushing: it changes nothing that leaves the machine. While something is staged and a commit is not yet pushed, Amend last commit folds the staged changes into the last one, keeping its message, and Fix up a commit records a fixup! of the one chosen among those not yet pushed — the terminal’s A and f — each after a last look at the commit it rewrites. A rebase, a hook, an amend and a fixup each show their output as it is written, with Stop, which stops the program and all it started, then how it ended, with Close. One goes at a time, and it holds the index, so a stage, a commit, a checkout or a setup of lefthook’s hooks asked for meanwhile waits for it. It goes on to its end if the page is closed, and a page opened meanwhile shows it running with its last lines. A conflict stops a rebase midway, for a terminal to finish.

When the repository’s .git/hooks holds hooks lefthook does not manage, and it configures no lefthook, Set up lefthook shows the hooks and the lefthook.yml that runs them, as the terminal’s g offers it; Write lefthook.yml writes it and installs lefthook, and Write every hook as a script keeps each hook whole under .lefthook instead. lefthook keeps the old hooks as .git/hooks/*.old.

Review

The branch’s pull request — its number, title and state: Draft or Ready for review while it is open, Merging while GitLab merges it, when nothing is offered on it, Merged or Closed once it is done — and the issue it is for, linked to its page. While it is open, the section also shows its mergeability, approvals and requested changes, and its CI checks, headed by how many are done when the forge counts them and by how CI stands when it does not, as for a GitLab pipeline, or “No checks reported.” when there are none — “No checks reported yet.” until the head has reported none through ten minutes of the server’s reads: a failed one names the stage it ran in and why it failed, and Show log reads the end of any check’s log the forge keeps one for, passed or failed.

Under the state, the terminal’s Review pane’s writes, each offered only when it can go and each sent from a form that is its last look: Edit pull request reads its title and description afresh and Saves them, as e does; Merge, once it is ready for review, free of conflicts, approved with no changes asked for, and green or with no check reported on its head through ten minutes of the server’s reads, from its start and from each new head — until then its CI checks say none are reported yet, and the form then says no CI was reported in those ten minutes, and a forge that requires checks refuses it — reads the methods the repository permits and merges by the one chosen, as M does; Re-run failed checks, while its CI has failed, restarts the failed jobs, as R does, says when a failure had no job to restart, and restarts none on a GitHub commit with more workflow runs than it reads, saying to re-run them on the forge; and once it has merged, Finish the branch shows the three git commands it runs — switch to the base, pull it from the base remote, delete the branch — as F does, when deleting the branch loses nothing: it is at the commit that merged, or its upstream holds every commit on it, and it has no commit made after the one that merged, which the server fetches first when this clone lacks it; a fetch that fails is in the way too. When something is in the way, the section says what in its place, as the terminal does. The server reads the pull request and its CI again before each, so nothing goes on what the page showed a moment ago. A token without the scope a write needs is told in the forge’s own words, naming the scope.

With no pull request for the branch, Open a pull request composes one as workflow pr would and shows it as a form: the title, the base, the reviewers, assignees and labels, the description, and whether it is a draft. When the repository has several pull request templates, Template chooses the one the description starts from, as the terminal’s ctrl+t does, until the description is edited. The reviewers start as the code owners of the paths the branch changes, as the base’s CODEOWNERS names them, leaving you out; a team is written org/team and is requested as a team. Name another Base branch and leave the field, and the branch is read again past it: the title, the description and the reviewers you have not changed are proposed again from the commits that pull request would merge, and a base no branch answers to keeps the draft and says so. Open pull request pushes the branch first when it is not published, then opens it. If the forge would not add every reviewer, assignee or label, a warning says so.

Right after the page opens one, the section offers what the terminal and workflow pr offer next: Link it on the branch’s issue, and Move the issue to the review status your configuration names, when that move needs no fields filled in. A pull request opened in the terminal or with workflow pr gets neither offer here.

With messaging set up, the page also arms the pull request’s announcement as it opens: a line says Announces to #dev once CI passes. To drop it, press Stop waiting in the Slack section., and the messaging section shows it waiting, as one held with Announce when CI passes does — for the forge to list the pull request just opened, through a failed run, and up to ten minutes with no check reported. One armed as it opens never replaces another pull request’s announcement that waits or is being posted: none is armed, and the line says which one still waits. It tags those workflow announce --yes would propose, the linked code owners of its changes against the base it opens into and the groups that start checked, and, as a post from the preview does, whom it can when the Slack token lacks a scope. A draft is never armed, and the line says to announce it once it is ready; messaging.auto_announce: false arms nothing. The open’s answer carries the armed announcement as announcement (its automatic set), or why none was as not_armed.

The messaging service

The preview shows the announcement as it will be sent, in the service’s own markup: with Slack, a link reads <url|text> there, and Slack shows it as just the text (link markup).

Named for the service your configuration uses — Slack, Teams, Discord or Webhook. It shows where announcements go and who they are from. Announce to the service composes the announcement of the branch’s pull request and shows it, with the channel to send it to where there is a choice; Announce now sends it. Nothing is sent before that second press, and what is sent is the text shown: when the announcement changed in between — the pull request merged, say — nothing is sent, the page says so, and Announce to shows the new one. Once a pull request was announced at the moment it is at now — ready for review, or merged — from here, the terminal or workflow announce, the section says so in place of the offer, as the terminal offers no announcement it has made; each announcement made here is claimed in the store for the terminal and workflow announce too. One whose post began and was never confirmed — a session that stopped mid-post, or a service that never said whether it took the post or failed while taking it — may have gone out, so it is not offered again either: posting it again here is refused with announced_unconfirmed, saying when the post began, and workflow announce asks before posting it again. A store that cannot take the claim posts nothing (not_claimed), and a post the service did not say it took keeps its claim, saying so. With store.disabled nothing is claimed or kept, so once posted the section offers the announcement again and posts it again if asked. A pull request closed without merging is none to announce: the section asks for one to be opened, as it does with none at all. One GitLab is merging is at no moment to announce: the section says to announce it once it has merged, and offers nothing until then. Each announcement is claimed in the store before it is posted, so two pages, a page and a terminal, or two servers asking at once post it once, and the second is answered 409. One posted whose claim the store then cannot confirm — a full disk, say — went out all the same, and the line saying where it went adds The store did not confirm it; it is not offered again., as a held one does once it goes, and as the terminal and workflow announce say it; the server’s log says why, which those two print after the sentence.

Nothing is announced while a check has failed on the pull request. The server reads its CI again as it posts, whatever the preview showed, and a failed check keeps it from going, ready or merged alike, with a ci_failed problem the section shows; a CI the server cannot read keeps it from going too. A ready-for-review preview whose CI has a failed check offers only Announce when CI passes, and says why; a post refused for a check that failed after the preview opened previews it again, offering the wait. A merge has no CI to wait for, so its preview offers neither, saying to re-run the failed checks on the forge and announce it once they pass.

Edit, in the preview, turns the message into a box to change it in, as the terminal’s e opens it in your editor; Announce now then sends the text as edited. An edit still goes only while the announcement it began from is the one composed now: when the pull request merged since, nothing is sent, as for an unedited one. An edit emptied of text is refused.

Until the pull request’s CI passes, a ready-for-review announcement’s preview also offers Announce when CI passes, the terminal’s w: the server holds the announcement — edited or not, with its tags — and the section says Waiting for CI on #42 to pass, then announcing to #dev., with Stop waiting to stop it unposted, after which the section offers to announce it again. Below them, while a frame shows it waiting — whichever page held it — the announce button reads Announce now instead, drawn as a secondary control: it opens the same preview, and an announcement sent from it settles the held one as announced once it goes. A pull request just opened waits first for the forge to list it, and the section says so. The held one is posted once the forge reports the CI passed, and the section then says it was announced. A failed run does not drop it: the section says a check failed and it waits on a fix, and it goes once a later run passes; nor does a read of the forge, or a post, that failed — the section says what failed and that it tries again — until the reads, or the post, have failed for ten minutes, when it is dropped saying which, and how it failed last. A post the service refused drops it with the service’s reason; one it did not say it took drops it too, since it may have gone out, and only workflow announce posts that one again, after asking. While no check is reported the section says it waits for checks; after ten minutes of reads that heard none, counted from the last read that saw one, a read that failed not counting, it is dropped, saying to announce it by hand — a repository with no CI is announced by hand. CI that runs and reads the same — no check finished, failed or started — for two hours drops it too, saying CI on #42 has been running for 2h. When, before its CI passes, the branch’s pull request is another one, closed, merged, or one GitLab began merging, it is dropped and the section says why in red. It is bound to the branch it was asked for on: checking out another branch meanwhile neither posts it nor drops it, and Stop waiting is the way to stop it. Announce when CI passes over another pull request’s waiting announcement replaces it, and the section says so. An announcement sent now leaves the held one waiting until the post has gone, then reads it as announced, so the channel never reads it twice; one that fails leaves it waiting. The server, not the page, holds it: it reads the branch’s pull request and its CI for it every timing.ci_interval (twenty seconds unless set), straight from the forge, whether a page is open or not, and a frame only shows how it stands. It is kept in memory alone, so it is lost, unposted, if workflow --web stops or switches directory before the CI passes — as one held in the terminal is lost when the terminal closes — and a post under way then finishes, its claim keeping it from going twice.

With a Slack user token, a ready-for-review announcement’s preview also says whom it tags. Tag code owners lists the code owners of the branch’s changes: one linked to Slack shows their Slack name, one decided not on Slack says so, and one not asked yet has a field to choose a member of the channel the preview posts to, narrowed to the names holding what you type and following the channel as you change it (a team’s, of the workspace’s user groups), and a Not on Slack button. The choice is saved as you make it, for this and every later announcement on the same forge host, and the page says it was saved for next time; Announce now waits while a link is being saved, and a group checked meanwhile stays checked. Tag groups checks the user groups the repository offers; a group a team owning the changed paths is linked to starts checked and says it “owns changed paths”, and the rest start as you left them last time. Tags: above Announce now names everyone the post will tag; the tags go on a line after the text. The post tags only the people the preview showed: when a link changed in Settings or a terminal since, nothing is posted and the page asks you to preview again. A Slack token without a scope linking needs (users:read, channels:read, groups:read or usergroups:read) for the channel picked is named in a note, and the announcement still posts, tagging whom it can. Links are kept per Slack workspace: when Slack will not say which workspace the token is for, a note says so, nobody is offered, and the announcement posts untagged; Settings’ people and groups say the same. Under --dry-run no owner is offered to link. Teams, Discord and a webhook tag no one, and so does a Slack webhook saved in Settings while the server runs: tagging follows the configuration in effect.

Reviews

The pull requests on your forge that wait on your review, the longest-waiting first: where each is, who asks, how long it has waited, whether it is a draft, and how its CI stands, in the words the filter offers them by — CI none where nothing reports CI, it could not be read, or on GitHub the request is past the hundred waiting longest, whose CI alone is read — each with a link to open it and Copy URL. Where the forge holds more than it lists — GitHub’s search serves its first thousand, and a GitLab listing is read two thousand deep — a line says these are only the first. Sort lists them Oldest first, Newest first or By repository, which heads each repository’s requests with its name, the longest-waiting first within it — the orders the terminal’s O cycles through. Filter narrows them, as the terminal’s f does: a button for each repository, CI state, draft or ready, and author the queue holds, each with how many requests hold it. Values in one of those widen the list, and the four narrow it together. A value picked stays on offer, at zero, once no request holds it, so it can be unpicked; a repository or author the queue no longer holds comes last. The order and the filter chosen stay while you visit other sections. The section asks the forge when you open it, unless it asked within the last 30 seconds, and Refresh asks again.

Tasks

Your pending Taskwarrior tasks, most urgent first unless you sort them — what the terminal’s Tasks pane lists, in Taskwarrior’s violet: those for an issue the Issues list holds first, then the rest, under For my issues and Other tasks when there are both. A waiting task is counted below rather than listed, and an active context says it narrows the list. Each row marks whether the task is started, then its id, what it is, and quietly its issue, when it is due and its urgency. Sort orders each group by urgency, state, ID, tag, issue or priority, as the terminal’s O does, and sorted by tag or priority each row shows its tags or priority, as the filter names them: no tag or no priority for a task with none. Search keeps the tasks whose description, project, +tag, issue key or #id holds what you type, and the Filter chips narrow the list by state, priority, project, tag and whether a task has an issue, each with its count; pressing waiting lists the waiting tasks. A started task whose wait is still ahead is waiting there, and marked not started, while Taskwarrior still counts it started: its detail offers Stop, and it is not the started task the track shows. A value picked stays on offer, at zero, once no task holds it, so it can be unpicked, and a named project or tag, or a named priority other than H, M and L, that no task holds any longer comes last; a waiting task counts toward its state alone. The order and the chips stay while you visit other sections. The section reads Taskwarrior when you open it, when Refresh asks, and again once the earliest wait still ahead has passed, since that changes where a task stands with nothing written, rather than from the stream. It needs Taskwarrior 3.5.0 or newer, found as Configuration describes; without one it says why — and, where the task on PATH is another program, go-task most likely, that taskwarrior.program in the configuration file can name Taskwarrior’s, which applies once workflow restarts or switches directory. Settings shows the program but does not change it.

The line at the top adds a task from what you would type after task add, in Taskwarrior’s own grammar — project:web, due:friday or +review among the words — and says which task it added. The line is not read as a shell reads it: each space-separated word goes to Taskwarrior as an argument of its own, and quotes are passed on as typed, as Using workflow explains. The selected task shows its state, project, priority, tags, due date, urgency, id and issue, a link to the issue’s page and, when the Issues list holds the issue, Open in Issues. For a task that names an issue the page is the tracker’s, as the terminal’s o opens it; with the forge’s issues as the tracker, or for a task that names none, it is the task’s jiraurl, and only an http or https address. Then come Start or Stop, Mark done…, its annotations, and a line each to Annotate it and Modify it in the same grammar. Undo… reverts Taskwarrior’s last change, whatever made it, and Sync…, shown when the taskrc names a sync backend, syncs. Those three ask first and send nothing until confirmed — marking done runs the task’s hooks, Taskwarrior has no redo, and a sync sends your tasks off the machine — while Start and Stop act at once. Each write says what it did, and the list redraws from Taskwarrior’s answer at once; a write that was made when the list after it could not be read still says what it did, and the section reads the list again, so a write that landed is never reported failed and made twice by a retry. A task marked done while the list could not be read again stays in the list as last read, offering neither Start nor Mark done…, until the list is next answered, by that read or by another write, whatever the stream says of the task meanwhile; the section says it leaves the list once workflow next reads it. A write Taskwarrior refuses says why below its button, in Taskwarrior’s own words, with your home and data directories put in fixed words and any line naming a server left out; a failed sync answers in fixed words only, and task sync in a terminal shows why. A write that changed nothing — Start on a task already started, say, or Undo with nothing to undo — shows the sentence its 409 carries.

Once Taskwarrior has answered, the rest of the page shows your tasks too: the loop under the header ends with the task you have started and how long it has run, and opens this section; each Issues row marks how its issue’s tasks stand; and an issue’s detail has a Tasks card listing each of its tasks, with Start or Stop and Mark done… on each still to do. A task marked done there shows done at once; when the task could not be read again after the done, it stands as last read, with neither button, and the card says it shows done once workflow next reads it. While none is still to do, the card offers Track in Taskwarrior, which adds the task the terminal’s T would, annotated with the issue’s page, and says which task now tracks it. Until Taskwarrior has answered, and where it could not, none of them is drawn, rather than a claim that no task tracks the issue.

Summary

What you did, read back each time from where the work left a trace: the commits you wrote in the repository the server runs in and in every favorite that is one — each named, acme/web@abc1234, when there is more than one — the Taskwarrior tasks you added, annotated and completed and the ones you started that are still going, what you did to Jira issues, and the pull or merge requests you opened, had merged and reviewed on the forge, in any repository. It opens on the previous working day — yesterday, or on a Monday, Friday and the weekend after it — in the time zone the server runs in.

The day reads as a timeline: each hour down the left, and what was done in it beside it, the verb in the hue of the system it was done in — git’s, Taskwarrior’s, Jira’s or the forge’s — then what it was done to, linked where it has a page, and its title. A period of several days or months is headed by month and by day. A source that could not be read says why above it — naming the repository, when one of several could not be read — in words that never name a host, and one that had more than it gave says so. A source that is not set up — no token, no forge the base remote names, no Taskwarrior installed, no git user.email — is left out, and says so as guidance with how to set it up rather than as a failure. Copy as Markdown puts the summary on the clipboard. Post…, beside it once messaging is set up, opens a preview of the same Markdown and where it goes, as the Messaging section previews an announcement: Edit changes the text, the channel is chosen when Slack offers more than one — a webhook posts to the channel it is bound to, which the preview says — and nothing is posted until Post; the service shows the headings and the list its own way. The preview says how long the summary is against the most the service takes, and a summary longer than that is refused with how long it is, and nothing is sent. Nothing about the post is kept.

Earlier and Later move a period back or on — a whole month to the month, a whole year to the year, any other period by its own length — and Today shows today. The calendar below them — beside them on a wide window — shows a month, chosen by year and month, in which the arrow keys move a day or a week, Page Up and Page Down a month, and Home and End to the week’s ends; Enter or a click shows that day, and with Shift, the days from the first one shown to it. Whole month and Whole year show the month or the year the calendar shows. A period runs up to a year and a day.

Repositories

Where the server works, relative to what it changes: the repository it is in, then the path within it, muted, as ~/src/api/cmd; origin’s host and path, and Base, the repository pull requests merge into, beside it in a fork’s clone; and the configuration files that apply there, the repository’s over your home’s. The header carries the same place, briefly, as api/cmd, and opens this section.

Worktrees are the repository’s working trees, as git lists them, each with the branch it has checked out — or the commit, when detached — and whether git keeps it locked, or finds its directory gone; Switch offers to switch to one, other than where the server works and one gone. With none to list, outside a repository, the list is left out.

Favorites are the directories you keep, each with what is there now — a repository and its origin, a directory in no repository, or one not there any more. Add to favorites keeps where the server works, Remove forgets one, and Switch offers to switch to it.

Go to a directory… (g, as in the terminal) opens a dialog for any other. Its field lists the worktrees and favorites first, then the directories where the server works; type a path — from where the server works, from your home after ~, or from / — and it lists the directories in the one before the last slash, narrowed as you type a name after it: those starting with it first, then those holding its letters in order, the letters matched in bold, and each repository marked. The arrow keys choose, Enter goes into a directory or asks to switch to the place chosen, Backspace after a slash goes up — from your home, on to the directory it is in, as in the terminal — and the path above the field goes up further. Switch to, at the foot, names the place highlighted and asks too. A hidden directory is listed once the name typed starts with its dot, and a directory of more than a thousand says that the first thousand are shown, as the server reports its limit, and is listed again for the name typed; the list draws at most two hundred, and says how many more match. The dialog stays open while a switch it asked for runs, so its refusal is shown in it.

A switch is asked once more in the dialog, with Back to the list, then made: the server wires the directory as it wired the first, and every section is read again for it. A directory whose configuration did not load, or binds keys workflow refuses, is refused rather than served on the defaults. The section you are in, the views’ orders and narrowing and the Summary’s period stay; the issue shown stays when it is a Jira issue, which is the same wherever you work. A page that has not yet noticed a switch — another tab, say — has its writes refused until it reads again, and a switch is refused while a write is being made. Under --dry-run the switch and the favorites are held back with every other write, and browsing still works.

Settings

The configuration file in effect, a section at a time, chosen from the list beside it — or above it, in rows, in a window narrower than 1024 px: Jira, Messaging, Forge and pull requests, Commits and branches, Taskwarrior, Terminal and keys and Advanced (timing and the store), which save together, then People and groups and Local data, which save as you change them. An edit stays as you move between sections, and each section’s tab marks how many of its settings are changed and not saved, or, once one is refused, how many are left to fix.

A bar stays in view below whichever section is shown. It says how many settings are changed and not saved — a list counts once, however many of its rows changed — with Discard, which puts every section back as it was read, and Save changes, which writes the file; both are held while nothing is changed. It says Saving…, then Saved. A setting refused is marked beside itself, with why: a few are checked before anything is sent — Jira’s address, the branch template’s {key}, the timings, the issue trailer and the counts — and a save the server refuses names the settings it refused, which are marked the same way. The bar then says how many are left to fix and in which sections, and Show opens the first one’s section with the focus on it. A save held back by those first checks goes to the setting it was held back for, and leaves what the server refused marked. Changing a refused setting takes its refusal away. Going to another section of the page while settings are changed and not saved asks Leave without saving? first: Leave drops the changes and goes, Stay keeps them.

Jira’s views and headers, messaging’s channels and the branch prefixes are lists: Add a view (or a header, a channel, a prefix) puts a row in, and each row’s Remove takes it out with the next save. A header’s name is fixed once saved; to rename one, remove it and add it again. The keyboard part’s Rebind keys lists every action the terminal binds, each with the key it is moved to (ui.keys) and the default an empty one keeps; a key that clashes with another where both work at once is refused when you save, as the terminal refuses it as it starts. A credential is shown masked and kept as it is unless you type a new one. Above its field it says where it is kept: Stored in the file; for the Jira token, Kept in your keychain, for its host, Read from $JIRA_TOKEN (the variable jira.token_env names) or Printed by a command you set; for Slack’s client secret and refresh token, not in the file, where the macOS keychain may keep them; for the forge token, not in the file, read from the environment or the forge’s CLI when either has one — both come before a token the file keeps; or Not set. Once you type one, it says it replaces the stored one when you save. Beside each one the file holds — the Jira token, the forge token, Slack’s client secret and refresh token, the webhook URL and each Jira header — Remove… asks, then writes the file as it was read without it, leaving your other edits in the form for Save changes; it cannot be undone, and removing the client secret or the refresh token takes the access token made from them too. A change to the forge part — its token, host, kind or CLI — applies at once: the next call to the forge uses it, and the page names the forge it points at, with no restart. A change to the messaging part applies to the next announcement. A change to Jira’s address, its token or where the token is read from (Read the token from your keychain, or jira.token_env or jira.token_command in the file), its user or headers, or to whether this repository’s issues are listed, waits until workflow restarts or switches directory, as the part says: only then is Jira wired again. So does which view those issues lead: they stay with the JQL the first view had, so editing that JQL drops them from the first view, and putting another view first leaves them leading the view that was first. The rest of the Jira part — its project, review status, views and Markdown comments — applies at once. Slack’s user token is three fields — Client ID, Client secret and Refresh token; on macOS a save refreshes the token with them and keeps the secrets in the keychain rather than the file, and where the file already keeps them it keeps what you type (see Configuration). The access token and its expiry have no field: workflow writes them. On macOS a Jira token you type goes to the keychain item for the Jira address, never into a file, and Read the token from your keychain is saved checked, so a repository whose file points Jira at another address takes a token of its own here; a token the keychain will not keep saves nothing. A change to the Taskwarrior part waits until workflow restarts or switches directory, as the part says: workflow finds Taskwarrior as it starts in a directory or switches to one, and until then the Tasks section says to restart or switch directory rather than read Taskwarrior. What the form has no field for is kept unchanged when you save: version, jira.token_command, jira.token_env, and the Slack access token and its expiry. The task program is shown but not typed into: workflow runs it, and jira.token_command, as you, and reads the variable jira.token_env names, so they change only in the file itself, and a save over the API that carries another value for one is refused. Settings reads the file each time it opens, and a save checks that the file has not changed since: when it has (edited on disk, rewritten by workflow config init --force, or saved from another tab), nothing is written, and Reload reads it again in place of your edits so you can make the change again — the bar says so, with Reload. A save from another workflow at the same moment (the terminal’s Settings, workflow config init, a Slack login) is waited for and then counted as such a change, through a lock in workflow’s state directory; one that keeps the lock longer than ten seconds has the save refused with another workflow is saving the configuration, so nothing was saved; save again in a moment. An edit made by hand in the moment between the check and the write, or any change on a system that names no state directory, is still written over. When the file on disk is not valid, Settings says so in place of the form, and workflow doctor says what is wrong with it. A switch made while Settings is open, from another tab or the terminal, reads the configuration again in place: when it reads the same, byte for byte, and the same files apply where the server works now, as Repositories lists them, your unsaved edits stay in the form. Otherwise, a copy of the file in another worktree or clone included, the form shows the file where the server works now, and says your unsaved edits were for the directory left. Until both reads have answered, Save changes is held, so a save never writes your edits over a file they were not made for.

Setting up

With no .workflow.json where the server works, Settings asks what workflow config init asks instead of showing a form of defaults. First, where the file goes: the repository, where it applies across it, or your home directory, where it applies everywhere. Then Jira’s address and your personal access token, typed into a field that shows nothing of it. With the OS keychain wired (macOS), Keep the token in your keychain, out of the file is offered, checked, for either file: the token goes to the keychain item for Jira’s address, and the file holds "keychain": true, which reads it back. Unchecked, the file keeps it, readable only by you. Last, a Slack incoming webhook, saved unchecked; blank posts with your Slack user token after workflow slack login. A blank address or webhook leaves that part out.

Write ~/src/api/.workflow.json — named for the file chosen — checks the token with Jira first, saying Checking with Jira…. A check that does not pass says why, beside the button, and writes nothing; Write it anyway keeps the address and token unchecked — except an address that is not an https address, or http to this machine, or that carries a username and password, which is never kept. Once written, the server works with the file as it does after a switch: the event stream reconnects, every section is read again, and Settings shows the file with what was written said above it — whom Jira knows the token as, that the keychain keeps it, and, for a file in a repository git does not ignore, to add it to .gitignore. A server that could not take the file up at once takes it up as Settings reads it again, or, when it still cannot, says so and to restart workflow --web. So does a file made there since, by hand or by workflow config init: reading the configuration takes it up, and Settings shows it rather than the setup. A file already there is never written over. A write still running, such as a git run started in another tab, holds the setup back: it writes nothing, and says to set up again once that write has finished. The token and the webhook go only to the server on the loopback address, which takes them from no other page, and no answer carries them back. Under --dry-run writing is held back, and the form says so.

People and groups keeps what the announcement preview asks: a table of every code owner decided on this repository’s forge host, then the branch’s owners not decided yet, each with a choice of whom they are on Slack — not decided yet, not on Slack, or a member of the configured channel (a team, a user group) — saved as you change it. Forget… asks first, in place, and a forgotten owner is asked about again at the next ready-for-review announcement. Groups for the repository is a checkbox per user group in the workspace, kept with Save groups; a ready-for-review announcement offers those groups to tag. Each saves on its own, apart from the configuration, into kept.db, and the label kept is the one Slack’s directory gives. A group already saved keeps its label, so one Slack no longer lists, or a token that cannot read the groups, can still be kept or unchecked, and clearing every group needs no Slack at all. A token without a scope the choices need is named in a note. Under --dry-run the area says its changes are held back and its controls are off.

Local data shows where workflow keeps what it learns between sessions and a row for each database file: the cache (workflow.db) and the kept associations and favorites (kept.db), each with its size and what it holds. It is read each time Settings opens and saved apart from the configuration. Remove cache… and Remove everything… each ask first, in place, with Cancel and Remove; removing everything says that people and group associations will be asked again and your favorites go with them, and People and groups is read again to show them gone. What the removal did is said below the buttons, and the listing is read again. A file another program holds open fails the removal, and the area says why and reads the listing again, since a file that could not be deleted after the rest were set aside may leave others gone. A removal waits for a change to People and groups under way, and the other way round. Under --dry-run the buttons are replaced by a sentence saying removing is held back. It is the web’s workflow db-clean (see Using workflow).

What stays in the terminal

The web covers the loop’s main line. These stay with the terminal interface, or the command line, by decision rather than by oversight; most are written down as ideas in FEATURES.md or UX.md:

  • Offering a task change at the loop’s moments — starting the issue’s task when its branch is made or checked out, noting the pull request on it, completing it on a merge or a move to done; on the web those are the Tasks card’s and the Tasks section’s buttons, pressed when you choose.

When a request fails

A failed request says why beside the button that made it, in words meant for you, and the button is there to try again; a read that fails says why above Try again. While a section reads, a line beginning Reading says what. When the words do not say enough, Questions and troubleshooting has what to do for the common ones. Behind those words, the API answers a failed request with an RFC 9457 problem details object whose code a script can rely on, a request presenting no session among them (401, unauthorized); only the loopback, same-origin and --dry-run guards, which refuse a request before it reaches the API, answer in plain text. Web API errors lists the codes.

Scripting the API

These requests answer what a section shows, for a script on the same machine: eight reads, and the Repositories section’s three writes — a PUT that switches where the server works, and a PUT and a DELETE on one path that keep or forget a favorite. The page takes the first four reads from its stream, and makes the others as its sections need them. api/openapi.yaml describes each answer’s fields, and every other request the API serves.

RequestAnswers with
GET /api/branchThe checked-out branch: its base, its upstream, how far it is ahead or behind, and its commits
GET /api/changesThe working tree’s changes
GET /api/reviewThe branch’s pull request and its CI
GET /api/messagingThe messaging service, and where and as whom an announcement would post
GET /api/activityWhat you did from one day to another, or on the previous working day, nested by year, month, day and hour, with the Markdown to copy
GET /api/repositoriesWhere the server works — the directory, its repository and the path within, origin and the configuration files — and your favorite directories, each with what is there now
PUT /api/repositories/hereSwitch the directory the server works in; refused while a write is in flight
PUT / DELETE /api/repositories/favoritesKeep a directory as a favorite, or forget it
GET /api/directoriesThe directories in one, or those whose names start with a prefix, to browse for one to switch to; a listing cut short at its limit gives that limit as truncated_to
GET /api/tasksYour pending Taskwarrior tasks, most urgent first, waiting ones included, with the active context and whether a sync backend is set

Every request presents the run’s session, the part of the printed address after #session=, as Authorization: Bearer <session>; one without it is answered 401 with code unauthorized. The event stream, which a browser’s EventSource opens with no header of its own, also takes it as ?session=.

session=…  # the part after #session= in the address workflow --web printed
curl -s -H "Authorization: Bearer $session" http://127.0.0.1:13579/api/review

GET /api/repositories’s answer needs no server: workflow repositories --json prints the same object from the directory it runs in, and workflow summary --json prints what GET /api/activity answers for the same period.

POST /api/activity/post posts the Summary: from and to, the period it is of, text, its Markdown as GET /api/activity wrote it or as it was edited, and channel, or none for the configured one or a webhook’s own. The server renders the Markdown for the service as it posts it and keeps nothing of the post; it answers where the text went, in destination.

curl -s -H "Authorization: Bearer $session" http://127.0.0.1:13579/api/activity |
  jq '{from, to, text}' |
  curl -s -H "Authorization: Bearer $session" -H 'Content-Type: application/json' -d @- \
    http://127.0.0.1:13579/api/activity/post

The reads answer under --dry-run too, and the writes are refused there, as every write is. When git or the forge fails, the branch, changes and review reads answer a problem, so a script can tell a failure from nothing to show; the event stream carries the same problem beside the panel it emptied, in the snapshot’s problems, and a CI read that failed in the review’s ci_error. The stream’s first message may be a seed event instead of a snapshot: the view’s issues as the store last kept them, sent before anything is asked of the network; a script that reads snapshot events alone can ignore it. A service that is not set up — a Jira or forge token missing, a base remote that names no forge — is a problem whose code is not_set_up, its detail saying how to set it up, so a script tells it from a refusal; /api/activity marks such a source’s state not_set_up, apart from failed. The tasks read answers available: false and why, never a problem, when there is no Taskwarrior to ask; a Taskwarrior that is there but fails the read answers a problem.

The Tasks section’s writes are POSTs beside that read: /api/tasks to add a task, /api/tasks/track to track an issue, /api/tasks/undo, /api/tasks/sync, and start, stop, done, annotations and modify under /api/tasks/{uuid}/. Each answers the task list as it stands after the write, and a task Taskwarrior changed nothing on answers 409. A done of a task linked to an issue also answers that task as it stands done, in done, since the list no longer holds it.

GET /api/hooks lists the hooks lefthook configures: in runnable, those a run by hand can stand in for, and in git_only, those only git runs, each with the reason. POST /api/runs with {"kind": "hook", "hook": "pre-push"} runs one runnable names — or rebase, amend, or fixup with the commit to fix up — and answers newline-delimited JSON as the run goes: the run as it starts, a line for each line its program writes, and the run as it ended, with its state and outcome. A hook runnable does not name is refused with a 422. DELETE /api/runs/current stops it.

curl -sN -H "Authorization: Bearer $session" -H 'Content-Type: application/json' \
  -d '{"kind":"hook","hook":"pre-push"}' \
  http://127.0.0.1:13579/api/runs

People and groups read GET /api/people and GET /api/repo-groups, and write with PUT to each and DELETE /api/people?owner=; the choices come from GET /api/slack/members and GET /api/slack/groups, which answer a missing scope as a 200 naming it. GET /api/announcement?channel= checks an owner not yet linked against that channel’s members. POST /api/announce takes mentions: users, the people the preview showed tagged, and groups, the user groups checked. The linked owners it tags are read from what is kept, never from the request, and a post whose linked owners are not users is a 409. It also takes edited_text, posted in place of the composed announcement beside text, the one the edit began from, and when: ci_passes, which holds it until the CI passes and answers 202, with replaced_pull when it replaced another pull request’s; DELETE /api/announce/queued stops a held one, and each frame of GET /api/events carries it as queued_announcement, with its id, a new one each time one is held afresh, its state and, while it waits, waiting_on. The frame’s review.announced reads posted, unconfirmed, unknown or none. Two announcements asked at once post once, the other answered 409; while a held one is being posted, announcing, holding another or stopping it is a 409 too, and a stop refused changes nothing.

The issue writes sit under /api/issues/{key}/: GET and POST transitions list the status changes with the fields each needs and make one, PUT assignee assigns it, and POST worklog logs work on a Jira issue.