Tags

Label a version of your project with a name such as prod, then run, schedule or compare it by that name.

What a tag is

A tag is a name for one version of your project, such as prod or 2026-q4. It points at a commit, and you can move it later. Runs and schedules can follow a tag instead of a branch, so "always run what's in production" doesn't need a branch kept around for it, or a commit id copied around.

	Branch	Tag
Points at	The latest commit, and moves with every push	One commit, until you move it
Moves when	You push	You move it
Use it to	Work on changes	Name a version you want to run or compare

A tag can't have the same name as a branch.

Tag a version

Open the Branches dialog

In the Code tab, click the branches count (for example 3 Branches).

Tag a version

Open the … menu of a branch and choose Tag this version. Type a name (spaces become hyphens) and click Create tag.

The dialog also lists your tags. A tag's … menu has Move tag, to point it at another branch, and Delete tag. A branch's row shows the tags that currently point at its latest commit.

Typing the name of a tag that already exists moves it: the dialog says so and the button reads Move tag. Moving a tag changes what everything that follows it runs from then on, so move prod only when that is what you want.

From the command line:

harumi tags list
harumi tags set prod                      # the branch you are on (push it first)
harumi tags set prod --to release-2       # another branch
harumi tags set prod --to 3f2a9c1e        # a commit
harumi tags rm prod

See harumi tags for every flag. Tags are ordinary git tags, so git fetch harumi --tags --force brings them into a clone (--force because a moved tag differs from the one you already have).

Run a tag

In the Run options dialog (the caret next to Run), open the Branch or tag list. The tags are below the branches. Pick one and click Run.

harumi run --tag prod --watch

The run records the tag and the commit it pointed at when it started. Moving the tag afterwards doesn't change a run that was already started, and the run keeps showing both, for example prod @ 3f2a9c1e. Runs from a tag are marked with a tag icon in the run lists, the execution history and the dashboard's run picker.

A tag run is not a live-branch run

A run from a tag isn't a run of the live branch, even when the tag points at a commit on it. The dashboard's default run is still the latest run on the live branch, and share links still show only live-branch runs.

Schedule a tag

In the Schedule a run dialog (the Schedule button), pick a tag from the same Branch or tag list. A schedule follows a branch or a tag, never both.

harumi schedules add --cron "0 9 * * *" --git-tag prod

A schedule that follows a tag looks the tag up every time it fires, so it runs whatever prod points at then, and reads harumi.toml from that commit. This is the way to run what's in production on a timer without editing the schedule at each release.

Deleting a tag that a schedule follows is refused. Change or remove the schedule first.
If the tag no longer exists when a schedule fires, that run fails and says so.

Compare tags

Click Refresh comparison on the compare page: the Run a fresh comparison dialog lists tags after the branches, and you can tick them like branches. See Compare versions. A tag is looked up once, when the comparison starts, so every run of the comparison uses a fixed commit even if the tag moves meanwhile.

On the compare page, a run that came from a tag is flagged when the tag has since moved ("has changed since this run") or been deleted ("no longer exists"), and the Run a fresh comparison dialog opens with the tags the compared runs came from already ticked.

Good to know

Setting a tag takes the same permission as creating a branch. Reading them, and running one, takes the same permission as running a branch.
Share links run named branches only; they can't run a tag.
The API-key API reports the tag of a run (git_tag) but can't start a run from one. See the API reference.

On this page