Version history and going back

Eight things you edit in CodeHerder keep a saved history of every change: a workflow, a stage in your shared stage library, a wiki page, a skill, a task’s own fields, a task’s own definition, a stage rubric, and stage environments. Each answers “can I undo this?” a little differently. This page compares them side by side; the guide for each one covers its own history in full.

What carries a history

• A workflow — the pipeline a task’s type follows. See Customising workflows.
• A stage in your workspace’s shared stage library. See The stage library.
• A wiki page. See Workspace wiki.
• A skill. See Skills.
• A task’s own fields — acceptance criteria, a plan, and the like. See Editing and cancelling tasks.
• A task’s own definition — every native column a task has, from its title down to its base branch. See Editing and cancelling tasks for the full list.
• A stage rubric — the criteria a judge grades a finished stage attempt against. See Stage judging.
• Stage environments — the setup and tools a stage runs with. See Stage environments.

What a history row shows, and how to page it

Every history list reads newest first, and every one pages the same way: a batch of rows plus a cursor for the next batch, capped by --limit and continued with --cursor. Workflow and stage rows also carry a short Change summary, such as “Added stage qa” or “Reordered stages”. Beyond that shared shape, a row doesn’t look the same everywhere. Most name a version number, when it was saved, and who saved it, and carry a change note where the item supports one. Three are different: a task-definition row names a version number and when it was saved, but not who — a definition is captured automatically, not attributed to a person. A skill-version row is the same way, keyed by version number plus its own content hash, also with no author. A stage-rubric row is keyed by the rubric’s own content instead of a version number, plus who created it and when.

Only the owning workspace has history

History answers at the workspace that actually owns the record. A stage or workflow your workspace inherited from a parent group, or a built-in one you’ve never customised, has no local history here — ch stage list or ch workspace workflow show name the workspace that owns it, and that’s where you’d look instead.

Going back, one item at a time

Workflow. Open the type’s page and use its Version history panel, or run ch workspace workflow versions <type>. Each row has a Change column that sums up what that save did. Compare shows two versions side by side. Click Revert on the version you want, or use the CLI:

ch workspace workflow revert story 2
ch workspace workflow revert story 2 --migrate drafting=ready --change-note "Back to the two-step flow"

A revert writes the old content as a new version, and every earlier version stays in the history. If it would drop a stage that still has live tasks, CodeHerder asks you to pick a surviving stage for them first. On the CLI, repeat --migrate old=new for each one. Only owners and admins can read this history or revert.

Stage. Run ch stage versions <key> to read the history, with --limit and --cursor to page it. To go back, run ch stage revert <key> <n>. It writes a new version with the old label, settings and fields, and leaves the stage enabled or disabled as it was. Add --change-note to record why. Reverting needs an owner or admin. The app’s stage history lets you view and compare versions, but you revert from the CLI. See The stage library.

Wiki page. ch wiki versions <ref> lists the history; ch wiki revert <ref> <n> writes an old revision back as a new one, and the app’s page view offers the same Revert button. See Workspace wiki for the full detail, including why a revert can refuse a version whose own body was saved cut short.

Skill. ch skill versions <slug> reads the history and, with --version N or --hash <sha256>, prints one version in full. Revert is app-only: it needs an owner or admin, and only works on a skill your own workspace owns. Reverting makes the earlier version current again rather than stacking a new one on top. See Skills for the full detail.

Task field. The task page’s prior versions disclosure, or ch task fields versions <taskId> <key> from the CLI, is read-only — there’s no way to restore an old value. See below for what actually lands there.

Task definition. ch task versions <taskId> lists the history, newest first, with --limit and --cursor to page it; add --version N to read one saved version in full. This one is CLI-only — there’s no app panel for it — and read-only, the same as a task field: there’s no restore.

Environment. ch env versions lists the history and ch env revert <n> goes back. See Stage environments.

Stage rubric. ch rubric versions <key> lists the history. A rubric can’t be edited or deleted, so there’s no revert command either — going back to an earlier one just means posting its old content again with ch rubric create, the same key, which becomes the current version.

A task field’s history isn’t an edit log

A field’s prior versions don’t come from ordinary edits — writing to a field just changes its current value, no history kept. They come from a backward move: sending a task back to an earlier stage, the way a rejected review sends it back to build. Only then does CodeHerder archive the field’s current value before resetting it, so whoever picks the work back up can still see what was there before. An empty history means this field has never been reset by a backward move. Not every field resets on one, though. A field the earlier stage can still write keeps its value. So does the merge request link, until the change actually lands.

A task definition’s version number is a key, not a count

Every saved version of a task’s definition gets a number, but that number isn’t “how many times this task has been edited” — it’s drawn from one running sequence shared across every task in the workspace, so even a task’s very first saved version can show up as a large number. Read it as a label for that saved snapshot, not a tally.

CodeHerder only saves a new version when the definition actually changes: its title, description, type, status, priority, required capabilities, due date, parent, workflow override, requested agent, join policy, cost budget, or base branch. Saving a task without changing any of those doesn’t add a row. A task’s history also only reaches as far back as its first captured version — an older task that hasn’t been edited recently may have none yet, and ch task versions says so plainly instead of showing an empty list.

Related guides

• Customising workflows — a workflow’s own version history, Change column, Compare, and Revert
• The stage library — a stage’s version history in full
• Workspace wiki — a wiki page’s revision history, Compare, and Revert
• Skills — a skill’s version history, Compare, and Revert
• Editing and cancelling tasks — per-task fields, and a task’s own definition history
• Stage judging — a stage rubric’s version history
• Stage environments — environment history and revert