Using wf

New to Workfile? Start with Getting started.

Run wf inside a project that has a .workfile/ folder, or in any folder
below it. wf uses the nearest .workfile/ it finds. Use --dir to choose
where it starts looking.

Health: how does the board compare to policy?#

wf health
wf health --gate code_review
wf health --stage review
wf health APP-42

Plain wf health checks every ticket in your Jira search and sums them up in
four boxes. They always follow the order of your workflow.

• Summary: how many tickets are in policy and how many are out.
• Gates: which gates are failing, and for how many tickets.
• Stages: which stages hold tickets that break policy.
• Most common reasons: the requirement that fails most often for each failing
  gate.

The percentages work like this:

• For a gate, it is the failing tickets divided by the tickets that must pass
  that gate. A ticket must pass a gate if it is in, or past, the stage the gate
  guards. A ticket in todo does not count against code_review.
• For a stage, it is the failing tickets divided by all tickets in that stage.

Red means failing and green means passing. These are your terminal theme's own
red and green. If you pass --limit, only a sample is checked, and the summary
says so. Tickets with a Jira status that is not in providers.yml are shown as
"cannot check" and are left out of the percentages.

Want to see the tickets behind the numbers? Use --gate or --stage, or both
together. You get a list of the failing tickets in workflow order, with what each
one still needs. With --gate, only that gate's problems are shown. A ticket
that fails two gates appears under each. You can also name tickets, as in
wf health APP-42.

Health asks one question: do the ticket's facts today match at least one valid
path to its stage? A ticket in review that cannot match any path into review is
out of policy. A ticket in todo with a short description is fine if the
description is only needed to leave todo. On a board with branches, a ticket
needs one valid path. It does not need the gates from every branch. Done tickets
are checked too.

Workfile cannot see history. It checks what is true now, not what was true when
a ticket moved. See branches and current facts.

Status: what should happen next?#

wf status
wf status --me
wf status APP-42

The overview shows every stage of your workflow. Each ticket appears once, in the
most urgent group that fits:

1. Cannot check: its Jira status is not in your workflow.
2. Out of policy: a gate from an earlier stage fails.
3. Needs work: it is fine so far, but every move forward is blocked.
4. Ready to move: a move forward is open, or a valid return exists.
5. Done: it is finished and passes every earlier gate.

Inside a group, tickets closest to the end of the workflow come first. Every
missing requirement is explained. If an earlier gate fails as well, the current
gates are shown too.

Name a ticket to see the full picture:

• The ticket key links to Jira. Its title and assignee sit above the workflow.
• Arrows show every move in your workflow, including branches and returns. The
  current stage is underlined. The places it can go next are green if open and
  red if blocked. Other stages are dimmed.
• Each pull request shows its repository and links to GitHub. A short status
  tells you if the policy gates pass, if a review is missing, or if it has been
  merged. If a PR was not checked, it does not claim to pass. GitHub's own
  branch rules and checks still apply on top of your policy.
• The Transitions box compares each place the ticket can go with each gate.
  A green tick means pass. A red cross means fail. A dash means the gate does not
  apply there.
• Next steps lists what to do for each place the ticket can go. Each blocked
  destination has its own numbered list, so you can follow one on its own. Open
  destinations show the move you can make. Returns are marked with ↩.

For example, suppose QA needs a code review, and release needs the review plus a
waiver. The QA list has only the review. The release list has both. Workfile
never does the work for you. The lists are for you to carry out in Jira or
GitHub.

Finished tickets show any unmet requirements, or say that no next step is needed.
On narrow or wide terminals you still see the same information. Wide diagrams
become a plain list of connections, wide tables become one list per destination,
and long text wraps inside the boxes.

When you pipe the output, or set NO_COLOR, there are no colours or links. You
get a (current) marker, the same ticks and crosses, and the full ticket and PR
web addresses.

Test: do the connections work?#

wf test
wf test jira
wf test github another_github

Names are the connection names in providers.yml. With no names, every
connection is tested. If one fails, the rest still run.

For Jira, the test checks who the token belongs to and reads one ticket from your
search. It also reads label history if your gates need it. For GitHub, it checks
who you are, lists the repositories you can see, and runs a sample PR search. If
your Jira search or GitHub organisation is empty, the test tells you.

A pass means those reads worked. It does not prove you can see every ticket or
repository you meant to include.

Options#

You can put options before or after ticket keys. Use --me or --user, not
both. --gate and --stage must name a gate or stage from policy.yml. wf test takes --dir and help, but not the other filters.

wf status fetches up to the limit and then applies --failing. So wf status --failing --limit 25 checks 25 tickets. It does not promise 25 failures. To
find every failure, use --all --failing.

--me and --user look through your whole search and all linked PRs first, and
only then apply the limit. This takes more work, but you will not miss a ticket
just because it was not in the first 25. When you name tickets, the limit is
ignored, but the tickets must still be in your Jira search.

Who is "me"?#

By default, --me asks Jira and GitHub who owns your token. If you use a shared
service account, set your identity yourself in ~/.config/workfile/config.yml:

me:
  jira: your-atlassian-account-id
  github: your-github-login

A setting for a connection name beats a setting for a provider type. For
example, github_client beats github for a connection called github_client.
You count as involved if you wrote a PR or were asked by name to review it. Past
reviewers do not count, and neither do members of a team that was asked.

Personal files and settings#

The credentials file has one NAME=value per line. Blank lines, comments, a
leading export, and single or double quotes around values are all fine. Values
are read exactly as written, so nothing is expanded and no commands run. An
environment variable beats the file. On macOS and Linux, other users must not be
able to read the file, so run chmod 600 on it. On Windows, limit access in the
file's security settings.

Exit codes#

If no tickets match, the report says so and exits with 0. Reports only cover
the tickets that were checked. Tickets outside your search, your limit, your
permissions, or the GitHub lookback are not included. Press Ctrl-C to cancel
requests that are still running.