Skip to content

Link a git revision to the changesets in title

Scans a piece of text for #1234 topic references and attaches one git revision to a field on each topic it finds. Point it at a commit message, a branch name or any string sitting in the stash, and the changesets mentioned in that string end up carrying the revision.

There is no repository picker on the form. The revision you name already carries the repository it belongs to. Title is not a search box either, it is raw text that gets mined for ids.

Title merge #1234 #1235 #99 topic 1234 topic 1235 topic 99 Revision appended to Field, saved as User, history entry written no such topic: the op errors here, later ids are never reached

Fields

Title

Free text. The op cuts it at every space and newline, keeps the pieces that start with #, and reads the remainder of each piece as a topic id.

Punctuation stays attached to the piece it touches, so #1234 is found while #1234. and #1234,#1235 are not. Commit conventions that put a comma between references defeat the scan. Spaces are the separator that works.

${var} placeholders expand against the stash before the scan, so the realistic value here is a variable rather than literal text.

Text carrying no # piece is a silent no-op: no topics touched, no log line, no error, and the rule carries on as though the op ran cleanly. The op only errors out when it has never been configured.

Revision

The resource id of a git revision registered in Clarive. A branch name, a tag name or a commit id put here does not resolve to a revision and is thrown away when the topic is saved, even though the log line still claims the link was made.

Expands ${var}, and the usual source is Create a branch in a Git repository. That op returns a list with one revision id per repository it worked on, even when it worked on one repository. A ${var} that is the entire value of this field resolves to the list itself rather than to a single id, and a list is not a revision id, so the save drops it and no link is made. Index the entry you want: ${new_branch[0]}. Putting the same variable inside a longer string fails instead, with an error about an unexpected reference.

Values already present on the field are not added a second time, so re-running a rule over the same changesets leaves the field and the topic history untouched.

Field

The id of the target field on the topic form, as set in the form designer. Labels are not accepted.

The field has to be one that stores revisions, which in practice means a Revision box. Naming an id that the topic's category does not have is accepted and does nothing, which is the second way to get a run that logs success and changes nothing.

Topics of different categories can appear in one Title value. Each is saved against its own form, so an id that exists on one category and not another produces a partial result.

User

The account name written on the change. The fallback to clarive only covers the case where the field has never been configured. A box you have cleared and saved sends an empty name through, and the topic records that: the timeline entry and Modified by come out blank. Type a name rather than emptying the box.

Whatever you put here appears on the topic timeline and on the notifications the save triggers, the same as if a person had edited the topic by hand.

What happens during the run

Topic references are processed in the order they appear in the text, one save per topic.

A reference with no topic behind it is not skipped. The op stops on it with a record-not-found error naming that id, so a stale #1234 left in an old commit message is enough to fail the step. A save that fails for any other reason ends the op the same way. Earlier topics keep the revision they were given, later ones are never reached, and nothing is undone. Set Error Handling on the op to trap or ignore errors when a job should survive that, or put the op inside TRY statement.

The job log carries one line per topic that was linked, naming the revision and the topic. The wording is fixed. The op returns no value, so a Return Key on it puts an empty entry in the stash.

Nothing is registered for rollback. Left at its defaults the op repeats on a rollback pass, and because the append is deduplicated, that repeat neither helps nor harms. Untick Run Rollback to keep it off the reverse path, and remove links by editing the topic.

Combining with other ops

Create the revision before you link it. Give Create a branch in a Git repository a Return Key, then name an indexed entry of that variable in Revision.

When the scan text has to be assembled, SET var covers the simple cases and Code covers the rest, both placed ahead of this op.

Wrap the op in IF var condition THEN with a LIKE test when the text often carries no reference, so the rule skips the call instead of running it for nothing. The same guard is worth having where commit messages quote ids from another system, since one id with no topic behind it fails the step.

In a deployment rule, Load Job Items into Stash already puts the job's changesets in reach, so this op is for the references that live in text rather than in the job contents.

Examples

Link the branch a rule created to every changeset named in the merge commit message. Every id in that message has to be a live topic, or the op stops on the first one that is not.

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

Link to one changeset whose id another op worked out, writing the change under a service account.

Title      #${changeset_mid}
Revision   ${new_branch[0]}
Field      git_revisions
User       ci_bot