Configuration

workflow reads a single JSON file, .workflow.json.

{
  "version": "1",
  "jira": {
    "base_url": "https://jira.example.com",
    "token": "",
    "user": ""
  },
  "messaging": {
    "kind": "slack",
    "token": "",
    "webhook_url": "",
    "channel": "#dev-workflow"
  },
  "forge": {
    "kind": "",
    "host": "",
    "token": ""
  },
  "ui": {
    "mouse": true,
    "ascii": false,
    "color": ""
  },
  "taskwarrior": { "program": "", "disabled": false }
}

Run workflow config init and it asks for the Jira address and token and checks them, then asks for a Slack incoming webhook, which it saves unchecked, since a webhook cannot be checked without posting; leave it blank to post with your Slack user token, which workflow slack login sets up afterwards. It warns if the file would not be ignored by git, and writes what passed — nothing is echoed as you type a token or the webhook. Add --global to write it to your home directory, or --template to write a blank file to fill in by hand instead of being asked. With no file, the terminal interface and the web’s Settings ask the same questions in a form, where to write it first (Using workflow, Web).

Where it looks, and what wins

workflow looks for .workflow.json in the current directory first, then in each directory above it up to the repository root — the directory holding .git — and then in your home directory, so a subdirectory of a repository reads the repository’s own file. Outside a repository it reads the current directory’s own file and no other: a directory above it belongs to no repository you are working in, and may be one anyone can write to, such as a shared /tmp. Your home directory’s file is the home file wherever it is found from, your home directory itself included.

A file found in or above the current directory is layered over the one in your home directory. Your home file holds what every repository shares — the Jira address and token, the messaging service — and a repository’s file holds only what that repository changes. A repository’s file of just

{ "jira": { "project": "OSS" } }

keeps everything else from home. Setting by setting, the repository’s file wins: an object in both is merged key by key, and anything else it sets — a list such as jira.views, a string, an explicit false — replaces the home file’s. Each file’s keys are checked on their own, so a misspelled one names its file, and the two are then checked together, since two valid files can still disagree (a webhook at home and a Slack user token in the repository, say).

A credential is inherited only by the address it was written for. A repository’s file is part of a working tree you may have cloned from anyone, so one that points a section somewhere else does not take your home file’s credentials with it:

SectionAddressCredentials not inherited once the address changes
jirabase_urltoken, token_command, token_env, headers
forgehosttoken
messagingkindwebhook_url and the Slack user token (client_id, client_secret, refresh_token, access_token, expires_at)

A repository’s file that leaves the address alone, or repeats the home file’s, still inherits them, and one that moves it may set a token of its own. A Slack user token is only ever sent to Slack, so a repository naming another channel keeps it; a webhook URL is its own address. jira.keychain is no credential and is inherited either way: it reads the keychain item kept for the address in effect, so a repository that points Jira somewhere else reads the token kept for that address, never the one kept for your home file’s.

Only your home file may run a program or read the environment. Three settings do: jira.token_command runs a program, jira.token_env reads an environment variable and sends what it holds to Jira, and taskwarrior.program names the program run as Taskwarrior. A file found in or above the current directory — a repository’s, or the current directory’s outside one — that sets any of them to anything but empty is refused when it loads, with an error naming the file and the setting, and a save that would write one there is refused the same way. Set them in ~/.workflow.json, which the repository’s file layers over.

A save writes the repository’s file when there is one: Settings, the web’s or the terminal’s, writes only what differs from your home file, so a token inherited from home is never copied into a file in a working tree, and a later change at home still reaches the repository. Nor is a credential you type there — a token, a header’s value, a webhook URL, a Slack secret not kept in the keychain — or a setting only your home file may make: the save is refused, writing nothing, and you set it in your home file instead. A Jira token you type is the exception where workflow drives the keychain (macOS): it goes to the keychain item for the Jira address, never into a file, and the file saved reads it from there, so a repository that points Jira at another address takes a token of its own from Settings. A credential already in the repository’s file is kept, and can be removed. workflow config init in a repository, over a home file, starts from the home file’s settings — a question left blank keeps the home file’s answer — and --template writes an empty layer rather than blanks that would hide them. --global writes the home file.

The terminal’s Settings reopens workflow to apply a save. While a write is in flight, or when reopening would lose something, such as a commit message being written, it asks first, naming anything that would be lost, and staying keeps the save for when workflow next opens. With no directory to reopen in, the save waits for the next start.

The web’s Settings applies a change to Jira’s project, review status, views and Markdown comments at once. The rest of Jira’s settings are read once, when workflow --web wires the directory it works in, as it starts or switches there, so a change to them waits for a restart or a directory switch: the address; the token and where it is read from, jira.keychain or, set in the file alone, jira.token_env or jira.token_command; the user; the headers; and issues.forge. So does which view the forge’s 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.

Which files apply is decided as workflow starts or switches directory, and in the terminal also as Settings reopens it after a save. A repository’s .workflow.json made while the terminal or workflow --web is running — by hand, or by workflow config init in another terminal — is not read until then: Settings goes on reading and saving the files it found, so a save still writes your home file, and the new file’s settings take no effect. In the terminal that save goes to your home file all the same, but the reopen after it takes the new file up, so from then on what the repository’s file sets wins over what was just saved. Restart workflow, or switch to another directory and back, to take it up. The one exception is a directory where no file applied at all: there the web’s Settings takes up a file made since as it reads the configuration again, and serves it from then on (Web: setting up).

workflow doctor names every file in effect, and workflow config show names them on stderr, so there is never a question about which were read. When a file is refused, see Questions and troubleshooting: When the configuration file is refused.

Fields

FieldRequiredDescription
versionnoThe file format’s version, which workflow config init writes first. "1" is the only one this build reads; empty (the default) means the current one, and any other value is refused when the file loads rather than half-read against a format it was not written for.
jira.base_urlfor Jira as the trackerRoot URL of your Jira instance, e.g. https://jira.example.com. It must be https, or http only to this machine (localhost or a loopback address): every request carries the token and every jira.headers value. Leave it empty to use the forge’s issues instead: the Issues pane then lists the open issues assigned to you on your forge. An address that is not an absolute https URL, or http to this machine, or that carries a username and password, is refused when the file loads, without quoting it.
jira.tokenone of these four, with jira.base_urlPersonal access token.
jira.keychainone of these four, with jira.base_urltrue reads the token from the OS keychain item kept for jira.base_url (macOS), so the file holds no secret. Any file may set it. See the keychain. Defaults to false.
jira.token_commandone of these four, with jira.base_urlA program that prints the token, e.g. pass show jira/token. Your home file’s alone; see Where it looks. See below.
jira.token_envone of these four, with jira.base_urlAn environment variable that holds the token. Your home file’s alone, as token_command is.
jira.usernoOnly for instances requiring HTTP Basic. See below.
jira.viewsnoNamed issue lists (name + jql) the pane moves between with v. Empty keeps the one built-in list. See below.
jira.headersnoExtra HTTP headers sent with every Jira request, for a Jira reached through an SSO proxy that checks one. Values are masked wherever the configuration is shown. Two names that differ only in case are one HTTP header, and are refused. See below.
jira.projectnoThe Jira project key, e.g. PROJ. When set, only a branch naming a key in that project is read as an issue, so a name like fix/UTF-8-decoding is not mistaken for one. Empty (the default) falls back to a looser guard that rejects common technical tokens (UTF, SHA, CVE) by shape alone.
jira.markdown_commentsnoWrite comments in Markdown and have them posted as Jira’s wiki markup. On by default; false posts a comment unchanged, for one already written in wiki markup. A comment on a forge issue is always posted as written, since the forge renders Markdown itself.
jira.review_statusnoThe status an issue moves to once its pull request is open, e.g. In Review. Opening a pull request offers the move to this status by name. Empty (the default) makes no offer.
issues.forgenoList the issues assigned to you on this repository’s own GitHub or GitLab project beside Jira’s, at the head of the first issue list. Set it in the repository’s file, over your home file’s default. With no jira.base_url the forge’s issues are the whole list whatever it says. Defaults to false. Saved from the web’s Settings, a change waits for workflow --web to restart or switch directory, as a change to the first view does for these issues; see Where it looks.
messaging.kindnoService to post to: slack (the default when empty), teams, discord, or a plain webhook, spelled in lowercase; any other value is refused when the file loads. It decides the message body and link markup.
messaging.client_idfor a Slack user tokenYour Slack app’s client ID, which its rotating user token is refreshed with. Not a secret; workflow slack login writes it. Slack only, and never together with messaging.webhook_url.
messaging.client_secret, messaging.refresh_token, messaging.access_token, messaging.expires_atwritten by workflowThe user token’s rotating credentials, when this file keeps them — on Linux and Windows, or on macOS once they are here — rather than the keychain. workflow rewrites the last three on every refresh. All but expires_at are credentials.
messaging.webhook_urlfor a webhookIncoming webhook URL. This is a credential, not just an address. The only transport for Teams, Discord and a plain webhook; for Slack, set it or a user token, never both.
messaging.channelwith a Slack user tokenChannel to post in, e.g. #dev-workflow. You must be in it. A webhook carries its own. workflow announce --channel and workflow summary --post --channel post one message elsewhere instead.
messaging.channelsnoFurther channels a user-token announcement can go to, for a change that concerns another team, e.g. ["#platform"]. The announcement preview offers them after messaging.channel, which is always a choice; you must be in each. A webhook carries its own channel and offers none.
messaging.announcementnoSlack template for the review message, from {author}, {noun}, {title}, {url}, {key}, {summary}, {issue_url}. Empty, or any non-Slack kind, uses the built-in message.
messaging.auto_announcenoArm the announcement of a pull request the terminal or --web opens, to post once its CI passes. On by default; false arms nothing when the terminal or --web opens a pull request, as a repository with no CI may want. w, Announce when CI passes, --when-green and pr --announce still wait when asked.
forge.kindon-prem onlygithub or gitlab, in lowercase, for a host whose name says neither. Anything else, GitHub included, is refused when the file loads.
forge.hostwith forge.kindThe host forge.kind and forge.token are for, e.g. git.example.com.
forge.tokennoGitHub or GitLab token. Usually leave it empty — see below.
forge.clinoRoute forge API calls through the forge’s own command-line tool — gh for GitHub, glab for GitLab — instead of over HTTP, so the login that tool already holds carries the request. This is what reaches a forge behind an SSO gateway a bare token cannot. Falls back to HTTP when the tool is not installed. Defaults to false.
ui.mousenoCapture the mouse, so a click focuses a pane or selects a row. Defaults to true.
ui.asciinoDraw borders and glyphs in plain ASCII, in the interface and on the live line a command keeps while it waits. Defaults to false.
ui.colornonever turns off the system hues; bold, faint and the cursor stay. Empty (the default) draws them; any other value is refused when the file loads. NO_COLOR, set to a non-empty value, also turns them off.
ui.motionnoreduce draws every state still: the in-flight mark does not turn, in the interface or on the live line a command keeps while it waits, and a stage’s rule and the CI bar stand where they have got rather than filling. Empty (the default) moves them; any other value is refused when the file loads.
ui.accessiblenoAsk a form’s questions as plain prompts that take the whole terminal, one at a time, for a screen reader, instead of drawing the form over the screen. Defaults to false; the ACCESSIBLE environment variable, set to anything, does the same.
ui.notifynoRing the terminal (and raise a desktop notification where it relays one) when CI finishes; under --web, say so in the page’s header. Defaults to false.
ui.comments_shownnoHow many of an issue’s most recent comments the detail pane draws. Defaults to 5, which 0 also keeps; a negative count is refused when the file loads.
ui.keysnoRebind keys: a map from an action to the single key that triggers it, e.g. {"commit": "C"}. The help then shows the new key. See Rebinding keys for the actions.
ui.web_shortcutsnoTurn on the --web page’s single-key shortcuts: the terminal’s keys, ui.keys applied, pressed outside a text field. Defaults to false; ? and the command palette work either way. See Keys on the web.
timing.request_timeoutnoHow long each request to a service may take, and how long a quit waits for the writes still in flight, as a Go duration such as 30s. Defaults to ten seconds. See Timing.
timing.ci_intervalnoHow often CI is asked about while it runs, and how often the --web page’s stream asks the forge about the branch, as a Go duration such as 1m. Defaults to twenty seconds. See Timing.
branch.templatenoShape of a proposed branch name from {prefix}, {key} and {slug}. Must contain {key}. Defaults to {prefix}/{key}-{slug}.
branch.prefixesnoMap from issue type to branch prefix, e.g. {"bug": "bugfix"}. The type is matched without regard to case or surrounding spaces, so two types that differ only in those are refused; this replaces the built-in {"bug": "fix"} rather than adding to it.
branch.default_prefixnoPrefix for an issue type not named in branch.prefixes. Defaults to feat.
branch.slug_limitnoThe longest the summary’s slug in a proposed branch name may be, in characters. Defaults to 48, which 0 also keeps; a negative limit is refused when the file loads.
commit.default_scopenoScope the commit composer — and the --web commit form — opens with when no kept draft has one and no commit in this repository has used one yet, e.g. api; the scope last used wins once there is one. Must be a valid Conventional Commit scope. Empty (the default) opens with no scope.
commit.typesnoThe commit types the composer — and the --web commit form — offers and checks a subject against, in the order to offer them, e.g. ["feat", "fix", "chore"]. Each is a lowercase word; a branch whose prefix is one of them opens the composer on that type. Empty keeps the built-in Conventional Commit types; a type that is not a lowercase word is refused when the file loads.
commit.subject_limitnoThe longest a commit subject may be, in characters; the composer’s ruler counts against it. Defaults to 72, which 0 also keeps; a negative limit is refused when the file loads.
commit.refs_trailernoThe label of the trailer that names the issue in a commit body, e.g. Closes. Defaults to Refs. It is a single word with no colon; anything else is refused when the file loads.
pull_request.title_sourcenoWhere a proposed pull request’s title comes from: commit (the default) takes the branch’s oldest commit subject, issue the issue’s key and summary. Any other value is refused when the file loads. See Pull requests.
store.disablednoKeep nothing on disk between sessions: neither the conveniences nor what you decided — whom each code owner is on Slack, the groups each repository tags, your favorite directories. Defaults to false; the store never holds a secret. See What is kept between sessions.
taskwarrior.programnoThe Taskwarrior program to run, and the only one tried: an absolute path, such as /opt/homebrew/bin/task, or a name looked up on PATH; a relative path is refused when the file loads. Empty (the default) tries every task in an absolute PATH directory, in order, and keeps the first that is Taskwarrior 3.5.0 or newer; a Taskwarrior that has never been run, whose taskrc has a malformed line, or that cannot start ends the search there. A value with a line break or a NUL in it is refused when the file loads. Your home file’s alone; see Where it looks. A change applies when workflow next starts or switches directory. See Taskwarrior.
taskwarrior.disablednoTurn the Taskwarrior integration off even where Taskwarrior is installed. Defaults to false. A change applies when workflow next starts or switches directory.

Unknown keys are an error rather than being ignored. A misspelled key that loaded silently would look exactly like a credential you never set.

Jira token (on-premises / Data Center)

  1. Sign in to your Jira instance in a browser.
  2. Open your avatar menu → Profile → Personal Access Tokens.
  3. Create a token and copy it into jira.token, with your instance’s URL in jira.base_url.

Leave jira.user empty to authenticate with that token as a bearer token, which is what Data Center expects. Set jira.user only if your instance requires HTTP Basic authentication, in which case the token is used as the password. workflow doctor reports which of the two modes is in effect.

Jira behind single sign-on (Azure AD / Office 365, and others)

On-premises Jira is often reached through a single sign-on gateway. Whether workflow needs anything special depends on where that gateway sits.

First, find out whether the REST API accepts a token directly. Create a personal access token (avatar → Profile → Personal Access Tokens; you reach this once by signing in through the usual browser SSO), then:

curl -sik -H "Authorization: Bearer <token>" https://your-jira/rest/api/2/myself
  • 200 with your user as JSON — the API takes the token directly; SSO only guards the web UI. Put the token in jira.token and you are done. This is the common case for a SAML SSO plugin (including Azure AD / Entra ID federation).
  • A redirect to login.microsoftonline.com or an HTML login page — the API itself is behind the gateway (for Azure AD, an Application Proxy, which is what the MyApps portal publishes). A token alone will not pass it; read on.

A gateway that mints a bearer token (Azure AD Application Proxy, OIDC). Use jira.token_command to fetch a fresh gateway token each run — for Azure AD, the Azure CLI does this:

{
  "jira": {
    "base_url": "https://jira.example.com",
    "token_command": "az account get-access-token --resource api://<app-id> --query accessToken -o tsv"
  }
}

Run az login once; the token is sent as Authorization: Bearer like any other.

A gateway that checks a header of its own (Cloudflare Access, and similar). Add the headers it wants under jira.headers; they are sent with every request, alongside your Jira token, and their values are masked wherever the configuration is shown (a gateway secret is a credential):

{
  "jira": {
    "token": "<jira PAT>",
    "headers": {
      "CF-Access-Client-Id": "<client id>",
      "CF-Access-Client-Secret": "<client secret>"
    }
  }
}

A Jira token is still required — jira.headers adds the gateway’s headers on top of it, rather than replacing your Jira credential.

Issue views

By default the Issues pane shows one list: the open issues assigned to you. If you pick work from elsewhere too — your issues in a sprint, a team filter, or the unassigned pile — name those lists under jira.views and press v to move between them:

{
  "jira": {
    "views": [
      { "name": "My work", "jql": "assignee = currentUser() AND statusCategory != done" },
      { "name": "Sprint board", "jql": "sprint in openSprints() AND (assignee = currentUser() OR assignee is EMPTY) AND statusCategory != done" },
      { "name": "Needs triage", "jql": "project = OPS AND assignee is EMPTY ORDER BY created" }
    ]
  }
}

The first view is shown at start, v switches to the next, and the pane title names the one in use. Each view is any JQL your instance accepts. A view missing its name or its jql is refused when the file loads, rather than showing an empty pane with no way to tell why. With no jira.views at all, the built-in “assigned to me” list is the only one, and v does nothing.

Every view is scoped to your issues unless its JQL names the assignee. A view of sprint in openSprints() AND statusCategory != done alone is searched as

(sprint in openSprints() AND statusCategory != done) AND assignee = currentUser()

— an ORDER BY stays at the end — while the three views above, which each name assignee, are searched as written. So a view of someone else’s work, or of nobody’s, says whose: assignee is EMPTY, assignee in membersOf("my-team"), or, as the sprint board does, yours and nobody’s at once. The word is looked for anywhere in the query, in any case. The interface and workflow --web scope a view alike, and the web’s GET /api/views lists each view with the query it searches.

Keeping tokens out of the file

So the file need hold no secret, a Jira token can instead come from the keychain, a program or an environment variable (a Slack user token has a home of its own, below):

  • keychain reads the token from the OS keychain item kept for the Jira address; see below.
  • token_command runs a program and reads the token from its output, e.g. pass show jira/token or op read "op://vault/jira/token". The command is split on spaces and run directly — no shell — so wrap a pipeline in a script if you need one. When Jira refuses the token it printed, as once a short-lived one expires, workflow runs it once more and asks again with what it prints then; a change Jira made all the same, served anonymously, is not sent twice. That run can come while the interface or --web holds the terminal, so the command must not ask on it then: keep pass’s passphrase in gpg-agent’s cache, say, or use a command that needs none.
  • token_env reads the token from an environment variable, e.g. WORKFLOW_JIRA_TOKEN.

The file’s own token wins when set, then the keychain, then token_env, then token_command. workflow doctor --online reports which source each credential came from, without ever printing the value.

The Jira token is found the first time a command needs Jira, so one that never reaches it, such as workflow reviews, never runs its token command or reads the keychain. The interface and --web find it before they start, while a command that asks for a passphrase on the terminal can still be answered. A command that fails or prints nothing, or a variable that is empty, is reported as no token where the service was wanted, and the token is looked for again the next time.

The operating system’s keychain

The keychain is where a token belongs. On macOS, workflow keeps a Jira token there with the built-in security, linking nothing, in a generic password item named for the address it is for — workflow-jira https://jira.example.com — under your login name. Each Jira address has an item of its own, so the keychain can hold a token for every Jira you work with, and "keychain": true in a file reads the one kept for that file’s jira.base_url. Since an item is only ever read for its own address, jira.keychain is safe in any file: a repository’s file that points Jira at another address, set by you or by whoever wrote the repository, reads the item for that address — and finds nothing until you keep a token there — never the one for your home file’s. An address and the same one with trailing slashes name one item.

workflow config init offers to keep the token there for you, for your home file (--global) or a repository’s alike: it saves it in the item for the address you typed and writes "keychain": true into the file, so the file never holds the token. Settings — the terminal’s and the web’s — does the same with a Jira token you type, for the address in the form, whichever file it saves: your home file, or a repository’s that points Jira somewhere else, which then reads the token kept for its own address. A token the keychain will not keep saves nothing. To see or remove an item, use Keychain Access, or security find-generic-password -s 'workflow-jira https://jira.example.com'.

workflow gives each run of security 30 seconds, whether it keeps a token or reads one. When the keychain is locked, macOS asks you to unlock it: answer within those 30 seconds, or the save or the read fails, and the next one asks again.

Elsewhere workflow drives no keychain, and jira.keychain gives no token. On Linux, store the token once and point token_command at it by hand:

printf %s '<your token>' | secret-tool store --label='workflow jira' service workflow-jira
# then set, in .workflow.json:
#   "jira": { "token_command": "secret-tool lookup service workflow-jira" }

Messaging: Slack, Teams, Discord or a plain webhook

messaging.kind picks the service. Empty is read as slack, so a file written before this block was named messaging — it was slack then — needs slack renamed to messaging and a "kind": "slack" added; workflow doctor names the rename if you forget. Slack alone has two transports; the others post over an incoming webhook.

KindTransportLink markup
slackrotating user token or incoming webhookSlack mrkdwn <url|text>
teamsincoming webhookMarkdown [text](url)
discordincoming webhookMarkdown [text](url)
webhookincoming webhookbare URL, no markup

workflow doctor reports the service and the transport in effect.

Slack: a user token or a webhook

Set up one or the other. A file that sets up both — messaging.client_id, or any of the user token’s secrets, beside messaging.webhook_url — is refused when it loads, so it is always clear which one posts.

User token — posts as you, to the channel you choose

Posts go out as you, through Slack’s API, with a token that rotates: each access token (xoxe.xoxp-…) lasts twelve hours, and a refresh token (xoxe-1-…), which works once, swaps it for a new pair. workflow refreshes it for you before it runs out, and keeps each new pair.

  1. Create an app at api.slack.com/apps in your workspace, by hand or from a manifest with an app configuration token (Creating the app from a manifest, below).

  2. Under OAuth & Permissions, add the chat:write user token scope, and turn on token rotation. Slack does not let rotation be turned off again. Tagging reviewers and user groups in an announcement is optional and needs four more user token scopes: users:read and channels:read (and groups:read for a private channel) to match people to the channel, and usergroups:read to offer user groups. Without them the announcement posts untagged and names the scope to add; a token issued before you add them must be issued again, by reinstalling the app and running workflow slack login.

  3. Install the app to the workspace. Copy the refresh token it gives, and the app’s Client ID and Client Secret from Basic Information.

  4. Set messaging.channel to a channel you are in, then run:

    workflow slack login

    It asks for the client ID, then the client secret and refresh token without echoing them, refreshes the token once to prove them, keeps the token with messaging.client_id beside it, and says whose token it is.

Where the token is kept:

  • macOS: in the keychain, under workflow-slack, so the file holds no secret. If the file already holds the token’s secrets, it stays there.
  • Linux and Windows: in the configuration file, which workflow rewrites after every refresh — the file is written readable only by you, as config init writes it.

The client ID goes in the same file as the secrets, in the same write: the file that already holds them, or else your home directory’s where you have one, which every directory reads, so a login run inside a repository with a file of its own works from every other directory too. Where the keychain keeps the secrets, the client ID goes in your home directory’s file all the same, just before the keychain keeps them, and comes out again if the keychain refuses. A repository whose own file names another app’s messaging.client_id would override the one the login names there, so the login refuses before it refreshes anything and names that file. Secrets with no client ID beside them are a login that did not finish: workflow doctor names messaging.client_id, and a post says to run workflow slack login again.

Every post asks for the token anew and refreshes it when it has less than ten minutes left, and once more if Slack still calls it expired. Two workflows running at once — the terminal and --web, say — take turns through a lock the system holds on a file beside the store, so they never spend the same refresh token twice. workflow slack login and a Settings save that refreshes take the same lock, so a post never keeps its pair over the one they just kept. The system lets the lock go when its holder ends, so one left by a workflow that stopped mid-refresh never holds the next one up. workflow doctor --online refreshes it if it is due, and says whose it is, where it is kept and when it expires. Under --dry-run it uses the token as held, and leaves one due a refresh unchecked rather than write a new one.

The web’s Settings takes the same three answers. Where the keychain keeps the token, a save refreshes it once with what you typed — a field left blank keeps the keychain’s — and keeps the new pair there, never in the file; Slack refusing them is said at once, and nothing is written. A keychain that cannot be read, a locked one say, refuses the save before anything is spent: unlock it, then save again. Where the file keeps the token, what you type is written to it, and the next post refreshes with it, which is when a refusal shows.

Asking somewhere other than Slack — a hook for tests and proxies. Every request that carries the user token goes to https://slack.com/api, unless the WORKFLOW_SLACK_API environment variable names another address: a fake Slack a test runs, or a proxy in front of Slack. It is an environment variable and never a .workflow.json key, so a repository’s file cannot send your token anywhere. It takes an https:// address, or http:// only to this machine (127.0.0.1, ::1 or localhost); anything else is refused with an error naming the variable, and nothing is sent. A webhook carries its own address and is not affected.

Creating the app from a manifest

An app configuration token, from Your App Configuration Tokens at api.slack.com/apps, is not a token workflow can log in or post with, and neither is the refresh token generated with it, though that one starts xoxe-1- like the one workflow slack login asks for. The pair only manages apps, through Slack’s App Manifest API, and the configuration token lasts twelve hours; once it has expired, generate a new one on the same page. What it can do is create the app from a manifest, in place of steps 1 and 2 above, as Create New App → From an app manifest does on that page, and that app gives the client ID, client secret and refresh token workflow slack login asks for. It acts as you, with no more right than you have: where your workspace approves apps before they are installed, the install is a request to its administrators either way.

  1. Save the app’s manifest as manifest.json. The last four scopes are the optional ones for tagging; leave them out to post untagged:

    {
      "display_information": { "name": "workflow" },
      "oauth_config": {
        "redirect_urls": ["https://localhost/slack"],
        "scopes": {
          "user": ["chat:write", "users:read", "channels:read", "groups:read", "usergroups:read"]
        }
      },
      "settings": { "token_rotation_enabled": true }
    }
  2. Create the app with the configuration token. The read line waits, showing nothing, for you to paste the token and press Enter, which keeps it off the screen, out of your shell’s history and off curl’s command line:

    read -rs CONFIG_TOKEN
    printf 'Authorization: Bearer %s\n' "$CONFIG_TOKEN" |
      curl -s https://slack.com/api/apps.manifest.create -H @- \
        --data-urlencode manifest@manifest.json
    unset CONFIG_TOKEN

    The answer holds the app’s credentials.client_id and credentials.client_secret, and an oauth_authorize_url. Where it says "ok":false, its error says why: invalid_auth or token_expired is a configuration token mistyped or past its twelve hours, so generate a new one; invalid_manifest names the field at fault. Where that is the redirect address, put an https:// address you control in the manifest instead: all it has to do is leave the code of step 3 in the browser’s address bar.

  3. Install the app. It now appears among your apps at api.slack.com/apps, where OAuth & Permissions offers Install to Workspace and then shows the refresh token. Or install it from the terminal: open the oauth_authorize_url and allow the app. The browser then goes to https://localhost/slack?code=…, which does not load; the code in its address is good for ten minutes, and is exchanged for the token, the client secret pasted at the read line as in step 2:

    read -rs CLIENT_SECRET
    printf %s "$CLIENT_SECRET" |
      curl -s https://slack.com/api/oauth.v2.access \
        -d client_id=<client id> \
        --data-urlencode client_secret@- \
        -d code=<code>
    unset CLIENT_SECRET

    The refresh token is the answer’s authed_user.refresh_token (xoxe-1-…). It works once, so leave it for workflow slack login to spend.

  4. Go on from step 4 of the list above: set messaging.channel to a channel you are in, and run workflow slack login with the client ID, the client secret and the refresh token.

Incoming webhook — the two-minute option

  1. Create an app at api.slack.com/apps in your workspace.
  2. Turn on Incoming Webhooks, choose Add New Webhook to Workspace, and pick the channel it posts to.
  3. Copy the URL into messaging.webhook_url (with "kind": "slack").

The webhook is bound to the channel you chose, so messaging.channel does not apply and is not required. There is no scope to request and no token to keep fresh.

The trade-off is that a webhook posts and nothing else: it cannot tell workflow the message’s timestamp, so later events arrive as new messages rather than replies, and it can never post anywhere but that one channel.

Teams, Discord or a plain webhook

Create an incoming webhook in the service, set messaging.kind to teams, discord or webhook, and copy the URL into messaging.webhook_url. A user token and channel do not apply — the webhook carries its own destination. The notifier renders each message in the service’s own markup: Markdown links for Teams and Discord, and a bare URL for a plain webhook.

Your team’s own words (Slack)

By default the review message reads jacob opened a pull request: <link> and, on the next line, the linked issue. messaging.announcement shapes it to a house style — an emoji, a reviewers line, a group to mention. It is Slack mrkdwn, so it applies to the Slack kind only; the other services always use the built-in text:

{
  "messaging": {
    "announcement": "🚀 {author} opened {noun} <{url}|{title}> — {key} {summary}"
  }
}

The placeholders are {author}, {noun} (pull request or merge request), {title}, {url}, {key}, {summary} and {issue_url}. The rest of the template — text, emoji, and Slack markup like <{url}|{title}> for a link — is yours to write.

Every substituted value is escaped, always. A pull request title is anyone’s to write, and an unescaped <!channel> in one would ping everyone in the channel; escaping is what stops that, and it is not optional. You preview the message before it is posted, so you see exactly what will go out.

The forge token you probably do not need

forge.token is consulted last, and most people never set it. workflow looks for a GitHub or GitLab credential in this order:

  1. $GITHUB_TOKEN or $GH_TOKEN ($GITLAB_TOKEN or $GLAB_TOKEN for GitLab)
  2. gh auth token, if gh is installed and signed in to that host
  3. forge.token

So if you already use gh auth login, there is nothing to configure and no second copy of a credential to keep safe. workflow doctor --online reports which of the three it used, which is what answers “why is it using that one?”.

A gh that is stopped before it answers, at its own 30-second limit or when whatever asked gives up, as one waiting on a keyring that never unlocks is, has not said it holds no token. forge.token still gets its turn after it, and with none there the forge is reported as not reached, exit status 5 on the command line, rather than as no token found.

There is no glab step. glab reports its token through auth status, whose output is prose on standard error, and parsing prose is not something to put a credential behind — GitLab users set $GITLAB_TOKEN or forge.token instead.

forge.token is never reported as missing, because failing doctor for everyone correctly relying on gh auth login would be wrong.

Every token is for a host

Each of those answers for one host, the way gh and glab read the same variables, and a token is offered to the host it is for and to no other:

SourceIs for
$GITHUB_TOKEN, $GH_TOKENgithub.com, and an Enterprise Cloud tenant under ghe.com
$GH_ENTERPRISE_TOKEN, $GITHUB_ENTERPRISE_TOKENthe host $GH_HOST names
$GITLAB_TOKEN, $GLAB_TOKENthe host $GITLAB_HOST (or $GL_HOST) names, and gitlab.com when neither names one
gh auth tokenwhichever hosts you have signed gh in to
forge.tokenforge.host, and with no forge.host, github.com or gitlab.com

So a GitHub Enterprise Server at git.example.com takes GH_HOST=git.example.com beside $GH_ENTERPRISE_TOKEN, or gh auth login --hostname git.example.com, or forge.host beside forge.token. An Enterprise Cloud tenant such as acme.ghe.com reads $GITHUB_TOKEN as github.com does, but its forge.token too needs forge.host beside it. When no source has a token for the host, workflow doctor --online says which of these it would have read.

What the token needs to be allowed

Every call workflow makes to the forge carries this token, or the login gh or glab holds when forge.cli routes the call through them, so it needs the permissions below. Pushing is not one of those calls: git pushes with its own credentials. A token that may only read still shows issues, pull requests or merge requests, reviews and CI; a write it may not make is refused, and workflow says which forge refused it, what that forge asks for — GitLab’s api scope, or GitHub’s repo scope or, for a fine-grained token, the permission the table below names — and the forge’s own reason, in the same words in the terminal and the browser. A token the forge did not accept at all is told apart: it may have expired or been revoked. workflow doctor --online warns of a GitLab token that can read but not write, when GitLab will say what the token may do; for some tokens, such as an OAuth token, it will not, and doctor then says nothing.

GitHub

A fine-grained token needs these repository permissions, on every repository you work in:

PermissionAccessFor
MetadataRead-onlyReading the repository’s merge settings; GitHub adds it to every token
Pull requestsRead and writeFinding, opening and editing a pull request, requesting reviewers, reading reviews
IssuesRead and writeAssignees and labels on a pull request, and reading and closing a GitHub issue
ContentsRead and writeMerging a pull request
Commit statusesRead-onlyCI reported as commit statuses
ChecksRead-onlyCI reported as check runs
ActionsRead and writeListing workflow runs, and re-running failed jobs

The review queue searches only the repositories the token was granted, so a fine-grained token limited to one repository shows the reviews waiting in that one alone.

A classic token needs the repo scope, or only public_repo when every repository is public. gh auth login grants repo by default, so its token already has what workflow needs.

GitLab

A token needs the api scope. With read_api alone, workflow reads everything but every write is refused.

The scope is only half of it: GitLab also checks your role in the project.

RoleFor
DeveloperOpening and editing a merge request, and retrying a pipeline
Whichever role the target branch’s protection allows to merge (Maintainer by default)Merging a merge request
Reporter, or the issue’s author or assigneeClosing a GitLab issue

Reviewers and assignees the forge will not take

Reviewers are added best effort on both forges. GitHub turns down the whole request when it cannot ask one name, such as someone who is not a collaborator, so workflow asks again one name at a time. GitLab sets reviewers and assignees by id, and a username it does not know, or one it cannot look up, has none, so the merge request opens with the reviewers and assignees it found. Either way the pull request opens, and a note names the people left off.

CODEOWNERS proposes the reviewers

When a pull request is composed — in the terminal’s composer, the web form and workflow pr — its reviewers start as the code owners of the paths the branch changes. Nothing needs configuring; a repository with no CODEOWNERS proposes nobody.

  • Which file. The first that exists on the base branch, read as the forge reads it: on GitHub .github/CODEOWNERS, then CODEOWNERS, then docs/CODEOWNERS, with GitHub’s rules (the last matching line wins); on GitLab CODEOWNERS, docs/CODEOWNERS, then .gitlab/CODEOWNERS, with GitLab’s sections, default owners and ! exclusions. On GitLab the lines before the first header are the section named codeowners, and a later [codeowners] header adds to them. The base is read as the base remote’s copy when one has been fetched (origin’s, or upstream’s in a fork’s clone), so a stale origin/<base> gives stale owners — git fetch brings them up to date.
  • Which patterns. Each forge’s patterns read as that forge reads them. On GitLab a pattern matches a whole path: docs/ and /docs/ cover everything under a docs directory, while docs and /docs name only a file called docs, and docs/* only a directory’s direct children. A pattern without a leading slash, such as README.md, matches at any depth, and * matches dot files too. GitLab matches with Ruby’s File.fnmatch, so a pattern with a doubled slash matches nothing, and a class reads as Ruby reads it: [a-] holds a -, and [!] or [^] is any character. A pattern written twice in a section keeps only its later line. A GitLab line starting with [ and holding a ] is a section header, as GitLab reads it, so a pattern that starts with a class is written after a slash: /[Dd]ocs/ at the root, or **/[Dd]ocs/ at any depth.
  • Which paths. Those the branch changes since it left the base (git diff <base>...HEAD, a rename counting as both of its paths).
  • Which owners. @username owners are proposed as people and @org/team owners as teams. Owners written as an email address are ignored, since no forge can be asked to review as one, as are GitLab’s @@role owners. You are left out: nobody is asked to review their own pull request. On GitLab the owners are every @name GitLab finds in the text after the pattern, wherever it stands: a # there starts no comment, so docs/ @a # @b is owned by both, and a line whose text names nobody, such as docs/ # todo, has no owners rather than its section’s defaults. An optional GitLab section (^[name]) proposes its owners just as a required one does: the caret only makes their approval optional, and they are still the people who know those paths.
  • Teams. GitHub is asked for a team as a team reviewer when the team is the repository’s own organization’s; a team of another organization cannot be asked there, and is reported as not added. On GitLab a @group/subgroup owner stands for the group’s active direct members with the Developer role or above, who are each asked when the merge request opens; members inherited from a parent group are not, and neither are Guests, Planners or Reporters, who cannot approve. A top-level group is written @group, just as a user is: a name GitLab knows no user by is tried as a group and expanded the same way. For tagging on Slack, GitLab is asked the same of each bare owner: one it knows as a group is a team, and links to a Slack user group like any other.

A proposal that cannot be read — the diff fails, or the file cannot be read — proposes nobody rather than holding the pull request back. Either way the reviewers are only proposed: edit or clear them before opening.

On-premises forges need forge.kind and forge.host

workflow reads the forge from your git remote. github.com, an Enterprise Cloud tenant under ghe.com, and gitlab.com name themselves; git.example.com does not, and a GitHub Enterprise Server looks exactly like a self-managed GitLab from a remote URL alone — while their APIs live at different paths. Rather than guess and send a token to the wrong service, say which forge it is, and which host you mean:

"forge": { "kind": "github", "host": "git.example.com" }

forge.kind describes forge.host and says nothing about any other host, so a repository whose remote is somewhere else is still a host workflow cannot name. A forge.kind with no forge.host is reported as incomplete.

forge.kind only fills that gap. On github.com, a ghe.com tenant or gitlab.com it is ignored, because the remote is the better evidence.

The interface: mouse, ASCII and color

ui.mouse is on unless you turn it off. While the interface captures the mouse, your terminal’s own click-and-drag text selection stops working — which is the whole reason it can be switched off. Press m to toggle it for one session without editing the file.

ui.ascii swaps the box-drawing borders and the status glyphs for plain ASCII, for a terminal or font that draws them as boxes of question marks; the in-flight mark, in the interface and on the live line a command keeps while it waits, turns through |, /, - and \, or holds still on * under ui.motion: reduce, and the live line’s bar is drawn with = and -. There is no reliable way to detect that from inside a program, so it is a setting rather than a guess. workflow status --plain draws its line’s glyphs, and the live line it keeps on a terminal while it reads named directories, in ASCII for one run, whatever the file says.

ui.color set to never turns off the system hues — the blue, yellow, green and magenta of the spine, the cyan of the started task at its end, and the red of a failure — while keeping bold, faint and the reverse-video cursor, which carry the same meaning without color. Setting the NO_COLOR environment variable to a non-empty value does the same; set but empty, as no-color.org asks, it does not. The glyphs already say by shape what the colors say by hue, so nothing is lost.

ui.motion set to reduce keeps the terminal still. Otherwise a few things move, and only while they change: the in-flight mark beside a pane’s title turns while its read is out, and so does the mark on the live line a command keeps while it waits; a stage’s rule on the top row fills over about a third of a second when the stage completes; and the Review pane’s bar of CI’s checks springs toward the share finished. Nothing moves while the first screen fills in from what the services answer. Under reduce each is drawn at once where it has got; the states read the same either way.

ui.notify, off unless you turn it on, rings the terminal when CI finishes — passes or fails — so you can open a pull request, switch to something else, and be told rather than checking back. On a terminal that understands the OSC 9 notification sequence it also raises a desktop notification; the rest just ring. Under --web the page says it instead, in its header beside the stream’s state — “CI passed on #128.” — whichever section is open. While it is on and no timing.ci_interval is set, the Review pane polls CI every three minutes rather than every twenty seconds, since a notification you stepped away for is not in a hurry. An announcement waiting for CI reads it on a beat of its own, every twenty seconds, so it goes out soon after CI passes.

A setting left out of the file keeps its default.

Accessible forms

ui.accessible, off unless you turn it on, changes how the terminal asks a form’s questions — the fields a status change needs, the first run’s questions, a section of Settings, and where a pull request goes and what it says. Drawn over the screen, a form redraws its field, options and cursor at once, which a screen reader reads poorly. With it on, or with the ACCESSIBLE environment variable set to anything, the form takes the whole terminal instead, as $EDITOR does, and asks one plain question at a time; the interface comes back once it has its answers. A form whose prompts end before every answer is in sends nothing and says why.

Rebinding keys

ui.keys maps an action to the one key that should trigger it. The interface binds that key instead of the default, and the help — press ? — shows the new key, so what you changed and what the screen tells you never drift apart. An action you leave out keeps its default.

{
  "ui": {
    "keys": { "commit": "C", "comment": "ctrl+e" }
  }
}

A key can mean different things in different places — c comments on the Issues pane and commits on the Commits pane — so each meaning is a separate action you rebind on its own. workflow refuses to start, workflow doctor reports the problem, and Settings in workflow --web refuses to save it, when a map names an action that does not exist, moves jump-to-pane — its keys are the pane numbers, 1–9, which no one key can stand in for — or binds two actions that are live at the same time to one key. Each pane is a place of its own, and so is each overlay — a picker, a preview, a composer, a running command: an action that works in one place and an action that works only in another are never live at once, so they may share a key, and ? lists each pane’s actions under that pane’s own name, so a key two panes share is listed once under each. Two panes the --web page shows in one section are the exception: its Branch section holds the Commits pane too, and the page answers a key with the first control on screen bound to it, so a key two of their actions the page binds would share is refused — commit on push’s P, say. An action only the terminal answers, such as discard-change or new-branch, has no control on the page, so it may still share a key with the other pane’s. The pane numbers work on every pane, so an action live on one cannot take one.

The actions you can rebind, grouped by where they work, are:

  • Moving around: next-pane, previous-pane, up, down, first, last, scroll-up, scroll-down.
  • Issues: change-status, comment, assign, log-work, start-work, search-issues, filter-issues, switch-view, load-more, open-link, copy-link, refresh, track-issue.
  • Branch: new-branch, switch-branch, link-issue, rebase, push.
  • Commits: stage, stage-all, unstage-all, discard-change, commit, amend, fixup, run-hook, set-up-lefthook.
  • Review: open-pull-request, checks, rerun-checks, merge, finish-branch.
  • Your messaging service (named for it, Slack by default): post, people-and-groups, stop-waiting.
  • Reviews: sort-reviews, filter-reviews.
  • Tasks: start-stop, mark-done, add-task, annotate-task, modify-task, undo-task, sync-tasks, search-tasks, filter-tasks, sort-tasks.
  • Summary: earlier, later, today, calendar, copy-summary, post-summary.
  • Repositories: switch-directory, favorite-directory, go-to-directory, settings, local-data.
  • In a composer or preview: edit, edit-body, next-template, toggle-draft, toggle-breaking, verbatim, next-field, previous-field, cycle-type-left, cycle-type-right, toggle-option, worktree (in the branch creator), post-when-green (in the announcement preview), unlink-issue (in the link form, on a branch already linked), remove-cache and remove-everything (in Local data), save-settings and remove-entry (in Settings), link-to-slack (in the announcement preview; People and groups links the selected owner with the apply key, listed under On panes and in overlays), not-on-slack (in the announcement preview and in People and groups), forget-owner (in People and groups), show-log (in the checks list).
  • Writing a comment (in the comment box’s normal mode): insert, append, append-line, open-line, cursor-left, cursor-right.
  • While a command runs: stop, run-again, full-output.
  • On every pane: toggle-mouse, toggle-help and quit. No overlay answers them but the help, which closes on the key that toggles the help and quits on the quit key; no overlay answers the key that toggles the mouse.
  • On panes and in overlays: apply and close, wherever the bottom row offers them: every overlay closes, and all but the help, a job’s log and Local data apply; the owner picker takes enter and esc as they are, not as moved. And interrupt, anywhere, even while you type.

A key is named as its terminal name: a letter (C), or a combination such as ctrl+e or shift+tab.

run-hook was named run-pre-commit when it ran nothing but pre-commit; a map that still names run-pre-commit is refused as an action that does not exist, so rename it.

interrupt quits from anywhere, even while you type into a search or a comment, so it must stay on a key that neither types nor edits text, such as ctrl+q: a map that moves it onto a letter, a digit, a symbol, space, backspace or delete is refused.

An action that asks first — its press opens a last look, which apply confirms — cannot share a key with apply, or that key pressed twice would ask and then confirm: on enter, remove-everything would empty Local data at a double press. So push, rebase, discard-change, rerun-checks, mark-done, undo-task, sync-tasks, forget-owner, remove-entry, remove-cache, remove-everything and switch-directory are refused on apply’s key, and apply on any of theirs. For the same reason enter on a Repositories row switches nothing: switch-directory does.

The keys an overlay answers while one of its text fields has the cursor — worktree, toggle-breaking, toggle-draft, next-template, edit-body, next-field and previous-field — cannot take a key that field types, edits or moves its cursor with: a character; left, right, home and end; one of the readline keys ctrl+a, ctrl+b, ctrl+d, ctrl+e, ctrl+f, ctrl+h, ctrl+k, ctrl+u, ctrl+v and ctrl+w; a word key, alt+left, ctrl+left, alt+b, alt+right, ctrl+right, alt+f, alt+backspace, ctrl+backspace, alt+delete, ctrl+delete and alt+d; or up, down, ctrl+n and ctrl+p, which step through a field’s suggestions (the mouse wheel sends up and down too). Such a map is refused, since the overlay would take the edit for its own.

Keys on the web

workflow --web offers the same actions by the same names, read from the terminal’s own bindings with ui.keys applied, so a rebinding reaches both. The page binds those it has a control for — commenting, changing the status, staging everything, committing, pushing and the rest — and the pane numbers to its sections; ? lists them by group, as the terminal’s help does, and ctrl+k (or cmd+k) opens a palette of the section’s actions by name.

A key that acts the moment it is pressed surprises someone using a screen reader or speech input, so the page’s single-key shortcuts are off until you turn them on, in Settings or here:

{
  "ui": {
    "web_shortcuts": true
  }
}

? and the palette work either way, except while a confirm, a preview or a form that writes in place waits on your answer, which holds every key the page binds until it is answered. With the shortcuts on, a key still types into the field that has the focus — a search box, a form, the comment box — and acts only outside one. The page binds a key it can tell apart from the browser’s own: one character, such as c, C or /. An action moved onto a combination such as ctrl+e keeps its place in ? and the palette, without a key on the page, since the browser keeps those for itself.

Timing

The waits are set for a nearby network and a forge with room in its rate limit. When yours is slower or tighter, stretch them:

{
  "timing": {
    "request_timeout": "30s",
    "ci_interval": "1m"
  }
}
  • request_timeout bounds each request to a service — ten seconds unless set — including one forge.cli hands to gh or glab. Raise it for an on-premises host that is slow to answer. A failed CI job’s log is read to its end however long that takes, so over HTTP it is bounded by each wait for the next part of it rather than as a whole; gh and glab hand a log back whole, so through them the bound is on the whole read. It also bounds how long quitting the terminal interface waits for the writes still in flight (see Limits).
  • ci_interval is how often CI is asked about while it runs — twenty seconds unless set — and at most how often the --web page’s stream asks the forge about the branch. Lengthen it to spend less of the forge’s rate limit.

Each is a Go duration: a number and a unit, such as 30s, 1m or 1m30s. A value that is not a positive duration is refused when the file loads, rather than quietly falling back to the default.

Branch names

When you branch for an issue, workflow proposes a name. By default it is fix/PROJ-412-short-summary for a bug and feat/… for anything else — the Conventional Commit prefix, the issue key as Jira writes it, then a slug of the summary. You can shape it to your team’s convention:

{
  "branch": {
    "template": "{prefix}/{key}-{slug}",
    "prefixes": { "bug": "bugfix", "story": "feature" },
    "default_prefix": "feat"
  }
}
  • template places the three parts. {prefix} is chosen from the type, {key} is the issue key, and {slug} is the summary. An empty slug — a summary with no letters — leaves a clean name rather than a trailing hyphen.
  • template must contain {key}. Everything the interface does with a branch — resuming its issue, linking its pull request, choosing a commit type — reads the key back out of the name, so a template that hid it is refused when the file loads.
  • prefixes maps an issue type to its prefix. What you write here is the whole rule: a type you do not list takes default_prefix, not the built-in fix.
  • slug_limit caps the slug at that many characters — 48 unless set.

You can still edit the proposed name before creating the branch; this only changes where it starts.

Pull requests

When you open a pull request, workflow proposes its title from the branch’s oldest commit subject, which on a branch of Conventional Commits already reads as one. A team that titles its pull requests after the issue can say so:

{
  "pull_request": { "title_source": "issue" }
}

issue proposes the issue’s key and summary, such as PROJ-412: Fix token redaction, and falls back to the oldest commit when the branch names no issue or its summary is not known. commit is the default, and any other value is refused when the file loads.

Taskwarrior

The Tasks pane, and the Tasks section of workflow --web, drive Taskwarrior 3.5.0 or newer wherever it is installed; there is nothing to turn on. An older Taskwarrior is reported as too old rather than driven.

{
  "taskwarrior": { "program": "/opt/homebrew/bin/task", "disabled": false }
}

Finding it

Taskwarrior’s program is called task, and so is go-task, the Taskfile runner. So workflow does not take the first task on PATH at its word: it asks each task on PATH, in order, for its _version, and keeps the first that answers as Taskwarrior 3.5.0 or newer. A PATH entry that is not an absolute directory, such as bin or ., is passed over. Each is asked from the filesystem root, not the directory workflow runs in, so go-task finds no Taskfile to run: a _version task, or a catch-all one, in your repository’s Taskfile never runs. The one that answers is kept for the session. A Taskwarrior that has never been run, whose taskrc has a malformed line, or that cannot start at all ends the search there: it is reported, as below, rather than passed over for a task further down.

taskwarrior.program names the one to run instead, and then only it is tried. Give it an absolute path: a bare name is looked up on PATH like any command, so "task" is whichever task comes first — go-task, where that is first — not the Taskwarrior further down, and a relative path such as bin/task is refused, since it would name a different program in each directory workflow starts in. taskwarrior.disabled turns the integration off even where Taskwarrior is installed: the Tasks pane says so, and no mark, block or offer appears.

workflow finds Taskwarrior once for the directory it works in, as it starts or switches there, so a change to taskwarrior.program or taskwarrior.disabled applies when workflow next starts or switches directory. One saved from the web’s Settings waits too: until then, the Tasks section says to restart workflow or switch directory to apply it — never a reason that holds only for the settings workflow started with — and the rest of the page shows no task.

workflow doctor names the Taskwarrior it found, or why none is usable:

  taskwarrior found — 3.5.0 at /opt/homebrew/bin/task
  taskwarrior not usable — task on PATH is not Taskwarrior (go-task?); set taskwarrior.program, e.g. /opt/homebrew/bin/task
  taskwarrior not usable — installed but never run; run /opt/homebrew/bin/task once

A Taskwarrior that has never been run has no taskrc, and will not make one unless asked at a terminal, so it reads as never run; so does one whose TASKRC names a file that is not there. Run it once in a terminal, by the path workflow doctor names — where go-task comes first on PATH, a bare task runs go-task — and answer its question. A taskrc with a line Taskwarrior cannot read is reported as having a malformed line, without the line, which may hold a secret. A Taskwarrior that cannot start for another reason — an include it cannot read, a database it cannot open — is reported in its own words: workflow doctor and the Tasks pane show them, and the web’s Tasks section says Taskwarrior could not start and that workflow doctor says why.

Tasks and issues

A task tracks an issue by jiraid, the issue’s key, and carries jiraurl, its page — two attributes of Taskwarrior’s user-defined kind. bugwarrior’s Jira service writes the same two, so a task it made tracks its issue here too. workflow defines both on every read and write of your tasks, as command-line overrides, and never writes your taskrc; only _version and _show, which read no task, run without them. For task jiraid:PROJ-412 to work in your own shell, add them to it — workflow doctor names these four lines while your taskrc has no uda.jiraid.type:

uda.jiraid.type=string
uda.jiraid.label=Jira
uda.jiraurl.type=string
uda.jiraurl.label=Jira URL

A task created from an issue — T in the Issues pane, or Track in Taskwarrior on the web — carries:

  • the issue’s key in jiraid and its page in jiraurl;
  • the tag +jira;
  • the issue’s priority as Taskwarrior’s: H for Highest, High, Critical or Blocker, M for Medium or Major, L for Low, Lowest, Minor or Trivial, and none for any other;
  • PROJ-412: <summary> as its description, after --, so nothing in the summary is read as an attribute;
  • one annotation, the issue’s page.

With the forge’s issues as the tracker, jiraid holds the issue’s number and there is no page to note.

Reads, writes and contexts

  • Reads never write. Every read runs with Taskwarrior’s hooks off, so listing your tasks never fires an on-launch or on-exit hook — one that syncs, say — and never changes a task.
  • Writes run hooks. Adding, starting, stopping, completing, annotating, modifying, undoing and syncing run as task does in a shell, with hooks as your taskrc sets them: a Timewarrior hook starts and stops its timer with the task. Taskwarrior’s confirmation prompts are off for them, since there is no terminal to answer.
  • Waiting tasks are counted. The Tasks list reads your pending tasks and those that wait until a later date, and counts the waiting ones below the list rather than listing them.
  • The active context narrows the Tasks list, as it narrows task list, and its name is shown beside the pane’s title. The tasks that track issues — the Issues rows’ marks, an issue’s Tasks block, and the top row’s started task when it tracks one — are read whatever the context. A change to a task workflow names — start, stop, done, annotate, modify — reaches it even where the context hides it; a task added with a takes the context’s attributes, as task add does.
  • Sync is offered only when the taskrc names a sync backend.
  • --dry-run reads Taskwarrior as usual and holds every write back; the terminal interface says what it would have sent.

What is kept between sessions

workflow keeps a little state on disk so it can pick up where you left off — the commit scope you last used in a repository, in the interface or with --web (which reads it once), which pull requests you have announced — in the interface or with workflow announce, and at which moment, so neither announces the same one twice unasked — and the last issue list each view showed, in the interface or with --web, so either opens on it while the live one loads. It also keeps what you decided and could not be seen again: whom each code owner is on Slack, or that they are not, the Slack user groups each repository offers, and the directories you marked as favorites in the Repositories pane. It lives in two small SQLite databases under your platform’s data directory:

  • macOS — ~/Library/Application Support/workflow
  • Linux — $XDG_STATE_HOME/workflow, or ~/.local/state/workflow
  • Windows — %AppData%\workflow

workflow.db is the cache: the conveniences above, which a session makes again. kept.db, beside it, is what you decided — the people and group associations, and your favorite directories — and is never thrown away on its own. A favorite is kept as the directory’s path alone; whether it is still there, and whether it is a repository, is read from the disk each time.

Beside them are empty lock files, which hold nothing and are never a secret: slack-refresh.lock, which a Slack token’s refresh takes, and one config-<hash>.lock for each configuration file workflow has saved, named from the file’s path. A save of the configuration — Settings, workflow config init, a Slack login — holds the lock of each file it reads from its check that the files are as they were read through its write, so two workflows saving at once never both write over the same revision: the second waits, then finds the file changed. It waits ten seconds at most, then refuses with another workflow is saving the configuration; try again in a moment. On a system that names no state directory, a save takes no lock. workflow db-clean leaves the lock files where they are; they are safe to delete while no workflow runs.

An announcement is claimed in the store before it is posted, so of every session and process announcing the same pull request at the same moment, one posts it. A store that cannot take the claim — a full disk, a file another program holds — posts nothing, since an announcement unclaimed could go twice, and says why; set store.disabled to post without a store, unguarded. One posted whose claim the store cannot then confirm went out all the same: the interface, workflow announce and the --web page add The store did not confirm it; it is not offered again.; the interface and workflow announce then say why, and under --web the server’s log does. Any other store that cannot keep what it is given never stops what was being done, and says so: a commit’s scope and an issue list not kept are said in the interface’s footer, and in the server’s log under --web.

Those associations are what tagging an announcement reads. Whom a code owner is on Slack is kept per forge host (github.com, say), since an owner is the same person in every repository there: a person links to a Slack user, a team to a user group, or either is marked not on Slack and never asked again. The user groups an announcement may tag, and the ones chosen last time, are kept per repository. Both are kept per Slack workspace too, the one the user token is for, which workflow asks Slack once a session: each link, listed group and chosen group belongs to the workspace it was made in, so one made in a workspace is neither used nor replaced in another, and switching back finds it again. That holds even for an ID more than one workspace sees — an Enterprise Grid user, a Slack Connect member, an org-wide user group. That an owner is not on Slack is kept per workspace as well, since a person may be in one workspace and not another. Whether an owner is a person or a team is kept once per forge host, so deciding it the other way in one workspace drops what was decided for the owner in every other, a Slack link or that they are not on Slack, and each of those workspaces asks again. When Slack cannot say which workspace the token is for, nobody is tagged: the announcement posts untagged and says why. The terminal’s announcement preview and the web’s ask whom an owner not yet decided is, and the web’s Settings and the terminal’s P overlay change or forget a decision; workflow announce tags only whom is already decided, and names the rest in its preview.

The store never holds a secret, and nothing it is keyed by is one. The commit scope and what was announced are kept per repository: the origin remote’s host and path, or the repository’s root path when there is no remote or it cannot be parsed. The issue list is kept per Jira instance, by a hash of your Jira URL, and per view, by the view’s JQL query. The store is never keyed by a credential, nor by the raw remote or Jira URL, so a token embedded in a remote cannot reach it.

Where the filesystem keeps Unix modes, each database file is 0600 in a 0700 directory, readable only by you. What the cache holds is disposable: remove it and the next session simply rebuilds it, and a cache a build with another schema made is discarded and rebuilt the same way. kept.db is never discarded: one a build with another schema made is read as empty and left as it is, and workflow says to run workflow db-clean --all to start it fresh.

A --dry-run never makes either file or changes what one holds. The interface and --web read nothing from the cache — Local data still counts what each file holds — and read kept.db read-only when it is already there, for whom an announcement would tag and your favorites; a command such as announce or status reads the file it needs the same way, and only when it is there. A dry run reads workflow.db as it is, whichever build made it, and a kept.db another build’s schema made as empty. Such a read may leave SQLite’s two owner-only companion files beside the file it read — kept.db-wal and kept.db-shm after a read of kept.db, workflow.db-wal and workflow.db-shm after one of workflow.db — until a session without --dry-run next opens that file and removes them.

To see the two files, their sizes and what each holds, and to remove them, run workflow db-clean (or open Local data in the web interface’s Settings, or with L on the terminal’s Repositories pane). It removes the cache once you confirm; --all removes kept.db too, and with it every people and group association, which workflow then asks for again. Each file goes with its -wal and -shm companions, and a file another program holds open — another workflow session, on Windows — fails the clean without removing anything. A file set aside that still could not be removed is listed as workflow.db.cleaning or kept.db.cleaning, and the next clean removes it. A running session simply makes a fresh cache on its next write.

The store is on by default. Set store.disabled to keep nothing on disk; with it set, workflow keeps nothing you decide and works the conveniences out afresh each time. No announcement tags anyone, since who is whom cannot be kept: the terminal’s ready-for-review preview lists each code owner it proposes as not linked and offers no link, and workflow announce and the web tag no one. No announcement is claimed, so nothing keeps one from going twice: not from two sessions, and not from one, since once it is posted the interface and the --web page offer it again and post it again if asked, and workflow announce posts it again without asking. No favorites are kept:

{
  "store": { "disabled": true }
}

workflow doctor names the store’s directory on its Store row — or says it is off, because of store.disabled or because no data directory could be found (no home directory, and no XDG_STATE_HOME or AppData to stand in), in which case the store keeps nothing and says nothing.

Keeping the tokens safe

.workflow.json holds live credentials:

  • workflow config init writes it mode 0600 — readable only by you — and --force leaves it that way whatever mode the file it replaces had.
  • workflow doctor fails while anyone but you can read or write the file, and names the chmod 600 that puts it right.
  • On Linux and macOS, a file someone else could have written is not read at all: one another user owns, one anyone else may write, or one a group may write that is not your own (the group with your user id, which a umask of 002 gives every file you make). workflow stops with an error naming the file, and chmod go-w on it puts it right.
  • A repository’s file, or the current directory’s outside one, may not be a link: a working tree can carry one to any file of yours, which a save would replace. Your home file may be one, as a dotfiles checkout makes it.
  • workflow config init warns when the file is not ignored by git; add it to .gitignore.
  • workflow config show masks every credential — Jira, Slack, the webhook URL and the forge token — printing only the last four characters so you can tell two apart, and none of one shorter than sixteen, such as a gateway’s header value, where four would give too much of it away.

messaging.webhook_url is masked like a token, because it is one. Anyone holding that URL can post to your channel; it is a password that happens to look like an address. workflow doctor never prints it at all — not even masked — because doctor’s output is what the bug report template asks people to paste.

Nothing in workflow prints a credential in full.