Fix a ticket end to end

Start a fix from a Jira card, work in its worktrees, save, open pull requests and close it.

You end up with a fix shipped from one command per step: a work item keyed to a Jira card, a branch and worktree in each repository it touches, pull requests into each base branch, and Slack posts for the team along the way.

You need:

What every workspace guide needs — see Before you start — and to be a member or lead of the workspace.
A workspace folder — see Set up a workspace.
For GitHub repositories, the GitHub CLI (gh) installed and signed in (gh auth login).

1. Start the work item

From the workspace folder, with the card's key:

crewkit work start CREW-123

crewkit creates the work item (its title comes from the card), fetches each repository's base branch from origin and cuts a branch and worktree in each:

  Work item crew-123-fix-login-redirect  CREW-123
  • /Users/you/code/acme/work/crew-123-fix-login-redirect/api

When the workspace has several repositories it asks which to work in; pass --repo api (repeatable) to choose up front. --title "…" overrides the card's summary. Starting a key that already has an open work item resumes it.

No card yet? Start from a description instead:

crewkit work start "login redirect loops"

crewkit searches the workspace's Jira project and lists the matches. Pick one, or pick Create a Task in CREW: … and confirm to create the card.

2. Work in the worktree

cd work/crew-123-fix-login-redirect/api
crewkit code

Commit as you normally would. The worktree is a regular git checkout on CREW-123-fix-login-redirect.

The workspace's agent settings are not written into worktrees yet, so a session here does not get them. They apply to a session started in the workspace folder itself.

Check every worktree at once from anywhere in the workspace folder:

crewkit work status

  work/crew-123-fix-login-redirect/api   CREW-123-fix-login-redirect   dirty 2 ahead of origin/main

Signed in, status also reports each branch's head and commits ahead to its work item, so your team sees it on the workspace page. A crewkit session in the worktree reports the same when it stops.

3. Save work in progress

crewkit work save

Inside a worktree it saves that work item; elsewhere, name it: crewkit work save crew-123-fix-login-redirect. Each worktree's uncommitted changes are pushed as a WIP commit to refs/crewkit/wip/<branch> on origin — your branch and working tree are untouched, so no CI runs. A host that refuses that ref namespace gets a wip/<branch> branch instead, which CI may build like any other branch. crewkit records only the commit's sha and time.

The first save of each repository on a machine asks Save api to its origin from this machine? Once you say yes, crewkit also saves a dirty worktree on its own every 10 minutes during a session and when the session ends.

4. Open the pull requests

crewkit work pr crew-123-fix-login-redirect

For each worktree crewkit asks Push CREW-123-fix-login-redirect to origin and open a pull request into main (api)?, pushes the branch and prints the pull request's URL. --repo api limits it to one repository. GitHub pull requests open with your own gh login.

The work item moves to In review.

5. Follow it through merge

Slack posts each step to the workspace's channel (once a Slack agent is set up). On the workspace page, the Work card shows the item's state, Jira status and last save; its branch count opens each branch with its head, commits ahead, push, last save and pull request state. From the CLI:

crewkit work show crew-123-fix-login-redirect

When the pull request merges and none is left open, the work item closes on its own — but only if your code host is connected: crewkit learns of the merge from its webhook and never polls. Without it the item stays In review, Slack posts no merge, and you close it yourself (step 6).

6. Close it

For a work item that ends without a merge, one whose merge crewkit was not told about, or to close it early:

crewkit work close crew-123-fix-login-redirect

The worktrees are kept; crewkit prints their paths so you can remove them when you are done.

If it stops

pick a card with crewkit work start <KEY-n>; creating one needs an interactive terminal — choosing from search results and creating a card need a yes on a terminal. Rerun in a terminal, or start with the card key.
crewkit work pr pushes and opens a pull request only after a yes on a terminal — work pr has no --yes. Run it in a terminal.
pass --repo <name> (one of: …) — without a terminal crewkit cannot ask which repositories to work in.
CREW-123 is not in this workspace's tracker projects — the card's project is not the workspace's Jira key (or a member project's). Check Jira project key in Settings.
This organization has no Jira connection, so CREW-123's title cannot be read from its card — pass --title "…".
this organization has no Jira connection — searching needs Jira connected; start with the card key and --title, or ask an admin to connect Jira.
no local clone of api in … — clone the repository into the workspace folder first.
api has base branch main, which its origin does not have — set the right base branch in Settings → Repositories.
the first save of api on this machine needs a yes on a terminal — run crewkit work save once in a terminal. Until then, automatic saves do nothing.
refusing to save files that look like credentials: .env — files named like credentials (.env*, *.pem, *.key, id_rsa, .npmrc, credentials*.json and similar) are never saved. An untracked one: add it to .gitignore or move it out of the worktree. One the branch already tracks: .gitignore does not help — untrack it with git rm --cached <file>, add it to .gitignore and commit. Then save again.
gh is not signed in — run gh auth login, then crewkit work pr again.