Skip to content

Link a git revision to the changesets in title

Reads a block of text, picks out every #1234 topic reference in it, and adds one git revision to a chosen field on each of those topics. The text is usually a commit message or a branch name the rule put in the stash earlier, which is how a commit that mentions a topic ends up linked to it without anybody opening the topic form.

The op does not search for a topic by its title, despite the field label. It reads ids out of whatever text you give it, and every id it finds has to be a topic that exists, or the op fails.

Title, split on spaces fix login for #1234 token starts with #? rest of it is the topic id no ignored, nothing logged yes does that topic exist? yes append Revision to Field, save the topic as User no op fails, rest never touched

Fields

Title

The text to scan. It is broken on spaces and newlines, and every piece that begins with # is treated as a topic id. Everything else in the text is ignored.

That splitting rule is stricter than it looks. #1234 is read. #1234, carries the comma into the id and matches no topic. #1234,#1235 is one piece, so neither id is found. Separate references with spaces.

The field expands ${var} against the stash, and that is how rules normally fill it. A commit message, a branch name such as feature/#1234-login, or a value you assembled with SET var all work.

Text with no # piece in it produces no work, no log line and no error. A box you have emptied behaves the same way. The op only stops with a missing-parameter error when it has never been configured at all.

Revision

The revision to add, given as the resource id of a git revision that already exists in Clarive. Not a branch name, not a tag name, not a commit id.

This is the trap on the page. A value that does not match a revision resource is dropped when the topic is saved, while the job log still reports the link as done. If a rule looks correct and the topic stays empty, the value here is the first thing to check.

The field expands ${var}, which is the normal way to fill it, with one catch. Create a branch in a Git repository hands back one id per repository it branched, as a list, and a variable written on its own resolves to the whole list rather than to a single value. ${new_branch} in this box therefore hands a list to a field that takes one id, and nothing is linked. Index the list instead: ${new_branch[0]} is the id for the first repository, ${new_branch[1]} the second.

Adding is additive and deduplicated. A revision already on the field is not added twice, and a second run of the same rule changes nothing and writes no second entry to the topic history.

Field

The id of the field on the topic form, not its label. Open the form designer and read the id off the Revision box you want to fill.

An id that does not exist on that topic's category is accepted without complaint. The topic is saved, but nothing is added to it. When the ids in Title span several categories, the same field id has to exist on each of them, or the ones that lack it are quietly left alone.

The field has to be one that holds revisions. Aiming this op at a plain text field does not convert the value into text.

User

The name recorded as the author of the change. The clarive default only covers an op that has never been configured. Once you have opened the config and saved it, an empty box is stored as an empty name and every topic the op touches records the change with no author against it. Type a name.

The name shows on the topic timeline entry and on the notifications the change sends, exactly as a manual edit would. Pick a service account name your team recognises when a job writes these links, so the history reads honestly later.

Order, failure and rollback

References are handled in the order they appear in the text. An id with no topic behind it is not skipped. The op fails on it with an error naming the id, and the job fails with it, so one stale #1234 left in a commit message is enough to stop a deploy.

Each topic is saved on its own. If a save fails, the op stops there: topics already handled keep their new revision, the rest are never touched and nothing is rolled back. Set Error Handling to trap or ignore errors when a link failure should not end the job.

Every link that is made writes one line to the job log at debug level, so it stays out of sight until you switch the Debug filter on. The wording is fixed. Nothing is written to the stash, so a Return Key on this op holds an empty value.

There is no undo. The op runs again on a rollback pass unless you untick Run Rollback, and because adding is deduplicated that second run is harmless rather than useful. To remove a link you have to edit the topic.

Combining with other ops

The usual shape is to create the revision first and link it second. Point the Return Key of Create a branch in a Git repository at a variable, then index that variable in Revision here, because that op returns one id per repository. Create a tag in a Git repository does not hand back ids, so it does not pair the same way.

When the text you want to scan is not in the stash yet, build it with SET var or read it in Code before this op runs.

To act only when the text carries a reference at all, guard the op with IF var condition THEN using a LIKE test for #. That keeps the log free of runs that had nothing to do.

Follow it with Change Topic Status when linking the revision should also move the topic along its workflow.

Examples

Link a branch created earlier in the same rule to whatever the commit message mentioned.

Title      ${commit_message}
Revision   ${new_branch[0]}
Field      revisions
User       release_bot

Link one revision to two topics named in a variable you built yourself. The space between them is what makes both ids readable.

Title      #${topic_a} #${topic_b}
Revision   ${new_branch[0]}
Field      git_revisions
User       release_bot