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:
| Section | Address | Credentials not inherited once the address changes |
|---|---|---|
jira | base_url | token, token_command, token_env, headers |
forge | host | token |
messaging | kind | webhook_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
| Field | Required | Description |
|---|---|---|
version | no | The 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_url | for Jira as the tracker | Root 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.token | one of these four, with jira.base_url | Personal access token. |
jira.keychain | one of these four, with jira.base_url | true 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_command | one of these four, with jira.base_url | A program that prints the token, e.g. pass show jira/token. Your home file’s alone; see Where it looks. See below. |
jira.token_env | one of these four, with jira.base_url | An environment variable that holds the token. Your home file’s alone, as token_command is. |
jira.user | no | Only for instances requiring HTTP Basic. See below. |
jira.views | no | Named issue lists (name + jql) the pane moves between with v. Empty keeps the one built-in list. See below. |
jira.headers | no | Extra 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.project | no | The 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_comments | no | Write 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_status | no | The 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.forge | no | List 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.kind | no | Service 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_id | for a Slack user token | Your 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_at | written by workflow | The 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_url | for a webhook | Incoming 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.channel | with a Slack user token | Channel 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.channels | no | Further 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.announcement | no | Slack 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_announce | no | Arm 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.kind | on-prem only | github or gitlab, in lowercase, for a host whose name says neither. Anything else, GitHub included, is refused when the file loads. |
forge.host | with forge.kind | The host forge.kind and forge.token are for, e.g. git.example.com. |
forge.token | no | GitHub or GitLab token. Usually leave it empty — see below. |
forge.cli | no | Route 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.mouse | no | Capture the mouse, so a click focuses a pane or selects a row. Defaults to true. |
ui.ascii | no | Draw borders and glyphs in plain ASCII, in the interface and on the live line a command keeps while it waits. Defaults to false. |
ui.color | no | never 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.motion | no | reduce 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.accessible | no | Ask 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.notify | no | Ring 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_shown | no | How 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.keys | no | Rebind 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_shortcuts | no | Turn 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_timeout | no | How 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_interval | no | How 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.template | no | Shape of a proposed branch name from {prefix}, {key} and {slug}. Must contain {key}. Defaults to {prefix}/{key}-{slug}. |
branch.prefixes | no | Map 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_prefix | no | Prefix for an issue type not named in branch.prefixes. Defaults to feat. |
branch.slug_limit | no | The 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_scope | no | Scope 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.types | no | The 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_limit | no | The 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_trailer | no | The 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_source | no | Where 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.disabled | no | Keep 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.program | no | The 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.disabled | no | Turn 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)
- Sign in to your Jira instance in a browser.
- Open your avatar menu → Profile → Personal Access Tokens.
- Create a token and copy it into
jira.token, with your instance’s URL injira.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/myself200with your user as JSON — the API takes the token directly; SSO only guards the web UI. Put the token injira.tokenand you are done. This is the common case for a SAML SSO plugin (including Azure AD / Entra ID federation).- A redirect to
login.microsoftonline.comor 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):
keychainreads the token from the OS keychain item kept for the Jira address; see below.token_commandruns a program and reads the token from its output, e.g.pass show jira/tokenorop 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--webholds the terminal, so the command must not ask on it then: keeppass’s passphrase in gpg-agent’s cache, say, or use a command that needs none.token_envreads 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.
| Kind | Transport | Link markup |
|---|---|---|
slack | rotating user token or incoming webhook | Slack mrkdwn <url|text> |
teams | incoming webhook | Markdown [text](url) |
discord | incoming webhook | Markdown [text](url) |
webhook | incoming webhook | bare 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.
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).
Under OAuth & Permissions, add the
chat:writeuser 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:readandchannels:read(andgroups:readfor a private channel) to match people to the channel, andusergroups:readto 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 runningworkflow slack login.Install the app to the workspace. Copy the refresh token it gives, and the app’s Client ID and Client Secret from Basic Information.
Set
messaging.channelto a channel you are in, then run:workflow slack loginIt 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_idbeside 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 initwrites 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.
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 } }Create the app with the configuration token. The
readline 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_TOKENThe answer holds the app’s
credentials.client_idandcredentials.client_secret, and anoauth_authorize_url. Where it says"ok":false, itserrorsays why:invalid_authortoken_expiredis a configuration token mistyped or past its twelve hours, so generate a new one;invalid_manifestnames the field at fault. Where that is the redirect address, put anhttps://address you control in the manifest instead: all it has to do is leave thecodeof step 3 in the browser’s address bar.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_urland allow the app. The browser then goes tohttps://localhost/slack?code=…, which does not load; thecodein its address is good for ten minutes, and is exchanged for the token, the client secret pasted at thereadline 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_SECRETThe refresh token is the answer’s
authed_user.refresh_token(xoxe-1-…). It works once, so leave it forworkflow slack loginto spend.Go on from step 4 of the list above: set
messaging.channelto a channel you are in, and runworkflow slack loginwith the client ID, the client secret and the refresh token.
Incoming webhook — the two-minute option
- Create an app at api.slack.com/apps in your workspace.
- Turn on Incoming Webhooks, choose Add New Webhook to Workspace, and pick the channel it posts to.
- 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:
$GITHUB_TOKENor$GH_TOKEN($GITLAB_TOKENor$GLAB_TOKENfor GitLab)gh auth token, ifghis installed and signed in to that hostforge.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:
| Source | Is for |
|---|---|
$GITHUB_TOKEN, $GH_TOKEN | github.com, and an Enterprise Cloud tenant under ghe.com |
$GH_ENTERPRISE_TOKEN, $GITHUB_ENTERPRISE_TOKEN | the host $GH_HOST names |
$GITLAB_TOKEN, $GLAB_TOKEN | the host $GITLAB_HOST (or $GL_HOST) names, and gitlab.com when neither names one |
gh auth token | whichever hosts you have signed gh in to |
forge.token | forge.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:
| Permission | Access | For |
|---|---|---|
| Metadata | Read-only | Reading the repository’s merge settings; GitHub adds it to every token |
| Pull requests | Read and write | Finding, opening and editing a pull request, requesting reviewers, reading reviews |
| Issues | Read and write | Assignees and labels on a pull request, and reading and closing a GitHub issue |
| Contents | Read and write | Merging a pull request |
| Commit statuses | Read-only | CI reported as commit statuses |
| Checks | Read-only | CI reported as check runs |
| Actions | Read and write | Listing 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.
| Role | For |
|---|---|
| Developer | Opening 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 assignee | Closing 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, thenCODEOWNERS, thendocs/CODEOWNERS, with GitHub’s rules (the last matching line wins); on GitLabCODEOWNERS,docs/CODEOWNERS, then.gitlab/CODEOWNERS, with GitLab’s sections, default owners and!exclusions. On GitLab the lines before the first header are the section namedcodeowners, 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, orupstream’s in a fork’s clone), so a staleorigin/<base>gives stale owners —git fetchbrings 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 adocsdirectory, whiledocsand/docsname only a file calleddocs, anddocs/*only a directory’s direct children. A pattern without a leading slash, such asREADME.md, matches at any depth, and*matches dot files too. GitLab matches with Ruby’sFile.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.
@usernameowners are proposed as people and@org/teamowners as teams. Owners written as an email address are ignored, since no forge can be asked to review as one, as are GitLab’s@@roleowners. You are left out: nobody is asked to review their own pull request. On GitLab the owners are every@nameGitLab finds in the text after the pattern, wherever it stands: a#there starts no comment, sodocs/ @a # @bis owned by both, and a line whose text names nobody, such asdocs/ # 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/subgroupowner 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-cacheandremove-everything(in Local data),save-settingsandremove-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-helpandquit. 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:
applyandclose, 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. Andinterrupt, 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_timeoutbounds each request to a service — ten seconds unless set — including oneforge.clihands toghorglab. 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;ghandglabhand 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_intervalis how often CI is asked about while it runs — twenty seconds unless set — and at most how often the--webpage’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"
}
}templateplaces 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.templatemust 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.prefixesmaps an issue type to its prefix. What you write here is the whole rule: a type you do not list takesdefault_prefix, not the built-infix.slug_limitcaps 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 onceA 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 URLA task created from an issue — T in the Issues pane, or
Track in Taskwarrior on the web — carries:
- the issue’s key in
jiraidand its page injiraurl; - the tag
+jira; - the issue’s priority as Taskwarrior’s:
Hfor Highest, High, Critical or Blocker,Mfor Medium or Major,Lfor 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
taskdoes 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 withatakes the context’s attributes, astask adddoes. - Sync is offered only when the taskrc names a sync backend.
--dry-runreads 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 initwrites it mode0600— readable only by you — and--forceleaves it that way whatever mode the file it replaces had.workflow doctorfails while anyone but you can read or write the file, and names thechmod 600that 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
002gives every file you make). workflow stops with an error naming the file, andchmod go-won 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 initwarns when the file is not ignored by git; add it to.gitignore.workflow config showmasks 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.