Create system tags

Writes the system tags a Git repository needs, one per active environment plus whatever extra names the repository's own Tags Mode calls for. The tag names are not yours to choose: they are derived from the repository's configuration, so a site with DEV, TEST and PROD and a repository left on the default mode gets those three names. These are the tags the lifecycle tree and the promotion machinery read to work out what each environment currently holds, which is why a repository that has never had them looks empty in those views.

Use it to initialise a repository that has been added to Clarive, or to reset the environment markers after a history rewrite. When you want a tag whose name you decide, use Create a tag in a Git repository instead.

The same action is available from a Git repository resource itself. Launched that way it works on that repository and the Repository field is not shown.

Fields

Repository

Shown when the op is used in a rule. The picker accepts several entries and offers variables as well as repository resources.

Only the first entry is used. Selecting four repositories tags the first one and ignores the other three, with nothing in the log to say so. To cover several repositories, place one op per repository, or wrap a single op in FOREACH CI and feed the loop variable in.

Existing Tags

What to do about a system tag that the repository already has.

Existing Tags	Behaviour
Don't replace existing tags	a tag that is already there is left where it is, and a line saying it was skipped goes to the log
Reset all tags	every tag in the list is moved to the chosen ref, whether it existed or not

Don't replace existing tags is the default. It is the safe option for a repository already in use, because it only fills in the names that are missing.

Reset all tags points every one of those tags at the same commit. On a repository that is already promoting through a lifecycle, that erases the record of what each environment holds.

Commit or Ref

Where the tags are placed. Any ref Git resolves works: a branch name, a tag, a commit id. Expands ${var} against the stash.

Leaving it blank does not mean the tip of the default branch. It means the oldest commit on the default branch, the very first commit in the repository's history. Every tag lands there, which reads as "no environment has anything" rather than "everything is current". If you want the current tip, type a branch name.

The field is a text area, but the whole of it is handed to Git as one ref. A second line is not ignored, it becomes part of the ref, Git cannot resolve the result and the op fails.

Tag Filter

Narrows the set of tag names to act on. Comma-separated, as the hint under the field says.

It is a keep list, not an exclusion list. With DEV,TEST in this field only those two tags are touched and everything else is left alone. Leave the field blank to act on all of them.

Entries are matched against the whole tag name, so a partial name matches nothing. Pattern characters work, so DE.* catches every name starting with DE, and PRE|PRO inside a single entry works too.

The filter is applied to the full tag list the repository asks for, release-prefixed names included, so DEV,TEST on a Release + environment repository writes the two bare environment tags and none of the versioned ones. .*-DEV picks the versioned DEV tags and skips the bare one.

A filter that matches nothing is a silent success: the op runs, writes nothing and reports no error.

What gets written and logged

The base tag names are the environments currently marked active. The catch-all environment is never tagged. On top of that list, the Tags Mode setting on the repository resource decides what else gets written:

Tags Mode	Tags written
Only environment	one per active environment, the default
Release + environment	those, and one <version>-<environment> tag for every release version
Project + environment	one per active environment, the same set as Only environment

Under Release + environment, a repository with DEV and PROD active and one 1.0 release gets four tags: DEV, PROD, 1.0-DEV and 1.0-PROD. The versions come from the releases of the projects attached to the repository, and a release whose status is of type Initial, Canceled or Final contributes nothing, so the tag set changes as releases open and close. That mode also needs at least one project linked to the repository. Without one the op stops with an error saying projects are required.

Project + environment gets no project-prefixed names out of this op. Promotion into such a repository works on <project>-<environment> tags, and those have to be put there another way, for instance with Create a tag in a Git repository.

Tags are lightweight, with no message, and they are always written with force, so the Reset all tags option moves existing ones rather than failing on them.

With Reset all tags the log gets one line per tag, naming the tag and the ref it is written at. With Don't replace existing tags a tag that is present produces a single line saying it exists and which commit it points at, and a tag that is missing produces two: a line saying it was not found, then the creation line. There is no setting that changes this.

The op returns the output of the tag commands, which is normally empty, so a Return Key on it is of little use.

Failure and rollback

Anything Git refuses stops the op, and tags written before that point stay written. There is no cleanup.

Both directions are enabled on a new op, so the op runs again during a rollback pass. With Don't replace existing tags that second run finds everything present and does nothing. With Reset all tags it moves every environment tag a second time, which is rarely what a rollback should do. Untick Run Rollback in that case.

Combining with other ops

Run it once after a repository is created, before any job tries to promote through it. A rule that creates repositories can end with this op so the lifecycle tree is populated from the start.

Pair it with Create a tag in a Git repository when you also want a named release marker at the same commit, and with Delete a reference in a Git repository to remove an environment tag that should not exist in a given repository.

Guard it with IF var condition THEN so a reset never happens outside the situation you intend, and use LOG around it to record which repository was touched, since the op names the tags but not the repository.

Examples

Initialise a newly added repository, putting every environment tag on the tip of the integration branch and leaving alone any tag that somebody already pushed.

Repository      ${repository}
Existing Tags   Don't replace existing tags
Commit or Ref   develop
Tag Filter

Reset the two lower environments to the current release commit and leave production where it is.

Repository      ${repository}
Existing Tags   Reset all tags
Commit or Ref   ${release_sha}
Tag Filter      DEV,TEST