Skip to content

Create a tag in a Git repository

Writes a Git tag straight into the central repository Clarive hosts. There is no clone, no working copy and no push: the tag exists the moment the op returns, and anyone who fetches the repository sees it.

Reach for it when you need a fixed marker on a commit, such as a release stamp or a name a later checkout can resolve. For a moving name that later commits can advance, use Create a branch in a Git repository. To stamp one tag per environment from the environment list rather than a name you type, use Create system tags.

Repository, in order repo A repo B repo C tag name already in that repository? no, or Force on yes, Force off tag written, move on to the next repository op stops, remaining repositories untouched

Fields

Repository

The repositories to tag. The picker holds more than one entry, and every entry gets the same tag name pointing at the same ref. Alongside the repository resources the list also offers variables, so ${repository} is a legal entry.

A variable that resolves to several repository ids separated by commas counts as several repositories, so a single ${repo_list} entry can fan out over a whole project. A variable holding a repository object works too.

Leave the picker empty and the op stops with a missing-repository error before anything is written.

Sha

The commit the tag points at. The label is narrower than the behaviour: any ref Git can resolve works here, including a branch name, another tag, a short or full commit id, or an expression such as master~2.

The field expands ${var} placeholders against the stash, which is how most rules fill it.

Nothing pre-checks the ref. If it does not resolve, the op stops and the error carries the Git command that failed together with its error output. Blank stops the op with a missing-sha error.

Tag

The tag name to create. Expands ${var}. Slashes are fine, so release/${version} produces a namespaced tag. The name is used literally, with no prefix added and no cleanup: a value with spaces, a leading dash or two consecutive dots is rejected by Git and fails the op.

Blank stops the op with a missing-tag-name error.

Force if already exists?

Off by default.

Off, a tag name that already exists in the repository fails the op. On, the existing tag moves to the new ref with no warning and no record of where it used to point. Turn it on for tags you expect to move, such as an environment or "latest" marker, and leave it off for release stamps you want to stay put.

What gets written

The tags are lightweight: a name pointing at a commit, with no tagger, no date and no message. No field on this form produces an annotated tag. Putting message text in Tag makes that text the tag name, which is a common way to end up with a repository full of unusable tag names.

Writing happens directly against the repository Clarive hosts, so the permission checks that apply when somebody pushes tags from a Git client are not involved. A rule that reaches this op can write any name, including the environment names used as system tags.

Failure, ordering and rollback

Repositories are handled one at a time, in the order they appear in the picker. The first failure stops the op there. Repositories already processed keep their new tag and the ones further down the list are never touched, with no attempt to undo the writes that did land. When you tag several repositories that have to stay in step, verify the result before you rely on it.

The op returns nothing. A Return Key set on it puts an empty value into the stash, so it is no use as a success flag. Reach for the op's Error Handling setting when you want a failure trapped rather than thrown.

Every new op runs in both directions by default, so a tag op left at its defaults runs again on the rollback pass. With Force off, that second run does not write anything: it fails because the tag name is already taken by the forward pass, and the rollback fails with it. With Force on, the tag is rewritten at whatever Sha resolves to on the rollback pass, which usually means the same commit and no visible change. Untick Run Rollback to keep the op out of the rollback pass entirely. The op has no undo of its own; build one with Delete a reference in a Git repository placed on the rollback path.

Combining with other ops

Tag the commit a branch currently points at by feeding the branch name straight into Sha, which saves resolving it first. When you do need the commit id in the stash, set it with SET var or compute it in Code ahead of this op.

To tag a list of repositories that is not known until the rule runs, wrap this op in FOREACH CI and pass the loop variable into Repository.

Pair it with Merge a branch in a Git repository to stamp the merge result, then with Delete a reference in a Git repository to retire the branch once the tag records where it was.

Examples

Stamp a release name on the commit a job is deploying, in a single repository held in a variable.

Repository   ${repository}
Sha          ${job_branch}
Tag          release/${release_name}
Force if already exists?   off

Move a marker so it always points at what last reached an environment. Force has to be on or the second run of the rule fails.

Repository   ${repository}
Sha          ${job_branch}
Tag          last-${env}
Force if already exists?   on

Tag the same commit across every repository a project owns, from a variable holding a comma-separated list.

Repository   ${project_repos}
Sha          ${baseline_sha}
Tag          baseline-${bl}
Force if already exists?   on