Commit Ticket Updater

Description

The Commit Ticket Updater is an optional component which makes Trac react on keywords and ticket references found in commit log message. Referenced tickets get a new comment linking to the changeset and depending on the presence of appropriate keywords, such as closed, fixed, reopened, the ticket status will be updated.

Hooks

That role was fulfilled by the trac-post-commit-hook​ for Subversion and previous versions of Trac (up to 0.11). Starting with Trac 0.12 and multiple repository support, a more general notification solution has been adopted.

The post-commit hooks now should simply use trac-admin to notify the TracEnvironment that a changeset has been added or modified. See TracRepositoryAdmin#ExplicitSync for more details. This works for any kind of VersionControlSystem supported by Trac and can notify that information to any kind of listener, not only the commit ticket updater, see TracDev/ApiChanges/0.12#IRepositoryChangeListener.

Location

The CommitTicketUpdater component lives in commit_updater.py​ and is maintained alongside the Trac core. It's included with every Trac installation as a plugin, but is not enabled by default because it's rooted in the tracopt. packages and not in trac.. Therefore it needs to be explicitly activated through the Admin interface.

Enable

1. Through the "Plugins" admin panel, enable: tracopt.ticket.commit_updater.* modules
   1. CommitTicketUpdater (tracopt.ticket.commit_updater.*)
   2. CommitTicketReferenceMacro (tracopt.ticket.commit_updater.*)
2. Alternatively edit the trac.ini file, by adding the following line in the [components] section:

   [components]
   tracopt.ticket.commit_updater.* = enabled
   

Configuration

There are also the following configurations to be set in the trac.ini file:

[ticket]
commit_ticket_update_envelope = []
commit_ticket_update_commands.close =
commit_ticket_update_commands.refs = <ALL>
commit_ticket_update_check_perms = true
commit_ticket_update_notify = true

Where:

• commit_ticket_update_envelope sets the required commands to be enclosed in an envelope.
  • Must be empty not to require an envelope;
  • or contain two characters. For example, if set to "[]", then commands must be in the form of [closes #4].

• commit_ticket_update_commands.close: has a space-separated list, with commands that close tickets.
  • Default values to close a ticket: close closed closes fix fixed fixes

• commit_ticket_update_commands.refs: has a space-separated list, with commands that add a reference to tickets.
  • Default values to reference a ticket: addresses re references refs see
  • If set to the special value <ALL>, all tickets referenced by the message will get a reference to the changeset.

• commit_ticket_update_check_perms when true checks that the committer has permission to perform the requested operations on the referenced tickets
  • Values: true, false

• commit_ticket_update_notify, when true send ticket change notification when updating a ticket.
  • Values: true, false

Sync Existing Commits

The trac-admin command that is executed in the post-commit hook can also be executed from the command line to update tickets for commits that were made prior to enabling CommitTicketUpdater. For example, to synchronize commits in the range r1 to r100 for a Subversion repository:

for r in $(seq 1 100); do
  trac-admin $env changeset added $repos $r;
done

Usage

The basic syntax is of the form [command] [ticketreference]. A colon between the command and the ticket reference is allowed. The ticketreference also allows to list multiple ticket numbers separated by spaces and/or comma. The word 'and' is also allowed between ticket numbers.

You can optionally refer to tickets with the following words:

• ticket, issue, bug

Examples (note: not verified!):

• close #10
• closed: #10
• closes #10
• closes ticket:10
• fixes #10
• fixes bug:10
• see issue 5
• references #5, #6
• fixes #10 and #11

Troubleshooting

Check permissions

If [ticket] commit_ticket_update_check_perms is True (the default), the changeset author must have TICKET_APPEND to reference a ticket and TICKET_MODIFY to close a ticket.

To support permissions checking in a Git repository the Trac username must be determine from the email address of the committer. Enable [git] trac_user_rlookup if permissions checking is enabled. The committer's email address in Git and Trac must match.