Install
What it needs
- git, always.
- lefthook, for running hooks on demand and for
turning existing
.git/hooksinto alefthook.yml. Without it those two actions are not offered; commits still run whatever hooks git has. gh, optionally, as a place to find a GitHub token, and as the toolforge.cliroutes GitHub calls through. See Configuration.glab, only withforge.clion GitLab, as the tool it routes GitLab calls through. Without it those calls go over HTTP. workflow does not read glab’s own login: over HTTP it takes$GITLAB_TOKEN,$GLAB_TOKENorforge.token, which needs theapiscope to write.- Taskwarrior 3.5.0 or newer, optionally, for
the Tasks pane and the
--webTasks section; without it they say so and nothing else changes. On macOS,brew install task. On Linux, your distribution’s package where it carries 3.5.0 or newer — many still ship 2.x, which is too old — or a build from Taskwarrior’s source, which needs Rust and CMake. Run Taskwarrior once, by its path where go-task comes first onPATH, so it writes its configuration. go-task, the Taskfile runner the source build below uses, is also calledtask; workflow tells the two apart, andworkflow doctornames the Taskwarrior it found, or why none is usable.
workflow doctor reports which of these it finds (gh and glab both,
whichever forge the repository is on), and workflow doctor --online warns
when a GitLab token can read but not write.
With Homebrew
On macOS or Linux:
brew install jacob-delgado/tap/workflowThis installs the release binary for your platform, checked against the
release’s checksum, or says so on a platform no release is built for. It comes
with completions for bash, zsh and fish, and brew upgrade workflow brings the
next release.
On Windows, download the release’s binary instead, as From a release says.
With Go
If you have Go installed:
go install github.com/jacob-delgado/workflow/cmd/workflow@latestThe binary lands in $(go env GOPATH)/bin, which needs to be on your PATH:
export PATH="$(go env GOPATH)/bin:$PATH"The binary carries the web interface (workflow --web) like a release binary
does; Go alone builds it, with no Node needed.
@latest resolves to the newest release tag. For a reproducible install, name
the version instead:
go install github.com/jacob-delgado/workflow/cmd/workflow@v0.14.0From a release
Each release
lists a binary for every platform it is built for, named workflow_<os>_<arch>
— with .exe on Windows — as workflow_darwin_arm64 is for Apple Silicon
macOS. Download the one for your platform, along with SHA256SUMS, then verify
and install it:
sha256sum -c SHA256SUMS --ignore-missing
chmod +x workflow_darwin_arm64
mv workflow_darwin_arm64 /usr/local/bin/workflowOn Windows, compare the hash PowerShell gives with the binary’s line in
SHA256SUMS, then rename it workflow.exe in a directory on your PATH:
(Get-FileHash workflow_windows_amd64.exe -Algorithm SHA256).Hash.ToLower()Every binary is built by GitHub Actions and carries a provenance attestation, so you can confirm it came from this repository’s CI rather than someone’s laptop:
gh attestation verify workflow_darwin_arm64 --repo jacob-delgado/workflowEach release also carries an SBOM, workflow.spdx.json, listing in SPDX format
the dependencies the binaries were built from — for checking them against
advisories or a policy.
From source
git clone https://github.com/jacob-delgado/workflow.git
cd workflow
mise trust && mise install
task build # builds bin/workflowThis needs mise, which provisions the pinned toolchain — Go and everything else the build expects. See Development for what else is in there.
First run
workflow config init # asks, then writes .workflow.json for you alone
workflow doctor # says what is still missingSet it up, answering the prompts, with workflow config init (--template
writes a blank file to edit) — Configuration
explains where to get the tokens — and run workflow to open the TUI. Or run
workflow, or workflow --web, with no file at all: each offers to set one
up, asking the same questions.
Using workflow walks through it. If a step
fails, Questions and troubleshooting: When something
fails says where to start.
Shell completion
Homebrew has already installed the completions for bash, zsh
and fish. Otherwise, workflow completion <shell> prints a completion script
for bash, zsh, fish or powershell. Source it from your shell’s startup,
and <tab> completes subcommands and flags — and workflow branch <tab>, and
every other command that names an issue first (issue, transition, assign,
worklog and comment), completes the keys of the issues assigned to you.
# bash — for this shell now, or add to ~/.bashrc
source <(workflow completion bash)
# zsh — write it where your completions live
workflow completion zsh > "${fpath[1]}/_workflow"
# fish
workflow completion fish > ~/.config/fish/completions/workflow.fishRun workflow completion --help for your shell’s exact one-time setup.