--- source: CrewKit documentation url: https://crewkit.io/docs/workspace-fix.md title: "Fix a ticket end to end" description: "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](/docs/workspaces#before-you-start) — and to be a member or lead of the workspace. - A workspace folder — see [Set up a workspace](/docs/workspace-setup). - 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: ```bash 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: ```bash 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 ```bash 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](/docs/workspace-handoff#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: ```bash 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 ```bash 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/` on origin — your branch and working tree are untouched, so no CI runs. A host that refuses that ref namespace gets a `wip/` 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 ```bash 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](/docs/workspace-setup#8-give-the-workspace-a-slack-agent)). On the workspace page, the **Work** card shows the item's state, [Jira status](/docs/workspaces#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: ```bash 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](/docs/workspace-setup#7-connect-your-code-host): 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: ```bash 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 ; 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 (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](/docs/workspace-setup#6-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 `, add it to `.gitignore` and commit. Then save again. - **`gh is not signed in`** — run `gh auth login`, then `crewkit work pr` again. --- ## Next steps - [Ship a feature with approval](/docs/workspace-feature) - [Workspaces](/docs/workspaces)