In this page

What are JQL variables?

JQL variables are simple dynamic placeholders that can be used in JQL searches executed by various commit conditions. They are represented in the format $variableName which are substituted with the actual values before Jira executes the actual search.

$committer.userName

Usage

As the value is inserted directly, wrap it with quotes: 

project = "Demonstration Project" AND assignee = "$committer.userName"

How does it work?

As you may know, Jira's built-in currentUser() JQL function can be used to obtain the currently logged-in user. With Better Commit Policy, it is most typically used to allow committing only against the issues assigned to the committer user, using a JQL like this: 

assignee = currentUser()

The problem is that in some situations the current user is not the same as the author of the commit! For example, with Subversion, there is a single hook script installed to the central repository and there is one user account configured in that hook script (more precisely in jcp_config.py). Therefore all verifications are done on behalf of that single user!

$committer.userName aims to solve this problem. The idea is that it evaluates to the author of the commit, which is passed in the commit's JSON representation by the VCS.

When to use it?

When to use the $committer.userName variable?

  1. For centralized VCS.
  2. For distributed VCS when having only a single central repository with all users committing directly to that.
    This is the same case as a centralized VCS, as it is also using a single hook script. (Note: we consider this scenario as a bad practice, as in this case you are not utilizing many advantages of the distributed VCS.)

When to use the currentUser() function?

  1. For Bitbucket.
    As requests from Bitbucket are sent using impersonating authentication, the currentUser() function is guaranteed to return the same user who pushes to Bitbucket.
  2. For distributed VCS when having multiple repositories (i.e. when using the distributed VCS as it is supposed to be).
    With these, we strongly recommend using one blessed repository and any number of forks with the "correct" hook script installed in each.
    What do we mean by "correct"?
    As you know, each hook script encodes that user who generated it in its authentication token. For the blessed repository, we suggest the project lead or the lead developer generate the hook script, and for the forks we suggest the owner of the fork. For local clones, it will automatically be the owner of the local clone (so that's correct any way).
Evaluating in various situations

This table summarizes how the two approaches work in various situations.

VCS $committer.userName evaluates to currentUser() returns
Subversion The commit-, branch-, tag author.
Recommended. 		The single user account configured in the central repository's hook script.
Not recommended.
Git (server-side, with a single central repository) The commit author. For branches and tags, it is the author of the first commit (or empty if there are no commits pushed).
Recommended. 		The single user account configured in the central repository's hook script.
Not recommended.
Git (server-side, with a blessed repository and separate forks for each user) The commit author. For branches and tags, it is the author of the first commit (or empty if there are no commits pushed).
Not recommended (as the other option is more secure). 		The user account configured in the blessed repository's and the forks' hook scripts.
Recommended.
Git (client-side, i.e. in local clones) The commit author. (Local hook scripts are not called when creating or deleting branches and tags.)
Not recommended (as the other option is more secure). 		The user account configured in the local clone's hook script.
Recommended.
Security considerations

Note that both Git and Mercurial allow freely configuring the user identity which will later be added to each commit. With Git, this is as simple as: 

git config --local user.name This_is_not_actually_me

If you don't have an authentication mechanism on your Git and Mercurial repositories (which is very likely to have), then this could allow developers faking their identity by using someone else's username. And, if someone is using a fake identity when committing changes, then the $committer.userName variable will evaluate to this fake identity. This is another reason why it is better to avoid $committer.userName for these VCSes.

Parsing the VCS username

The user name returned by $committer.userName is parsed from the userName field in the commit JSON like this:

userName field in the JSON $committer.userName value Notes
john.smith john.smith
John Smith <john.smith@acme.com> John Smith
john.smith@acme.com john.smith@acme.com When using VCS user names in email address format.
john.smith@acme john.smith When using VCS user names ending with some domain specification.
<john.smith@acme.com> (empty string) When not using VCS user names, but using VCS email addresses. (Git and Mercurial works with those separately, so it is possible to forget about the username.)

Questions?

Ask us any time.