Tickets, revisions, and releases for software development

This document shows how we use Tickets, Revisions and Releases here at Shotgun to manage our own software development process.  We'll first go through some out-of-the-box functionality, and then show you how we've customized our own Shotgun around our current workflow.


Video Tour

Here is a quick video that shows a bit how we use Tickets to manage our work here at Shotgun (the documentation below goes into much more detail):

Getting set up

Enable Tickets, Revisions, and Releases

The process of enabling these entity types is exactly the same as it is for any other entity type, and is described here. Once this is done, you can optionally enable the 'Tool' entity type. Enabling 'Tool' is useful if you'd like to organize various projects by Tool or Application, such as "Shot submit tool", "Hair Pipeline", etc. For those of you that use Scrum, you can use a Custom Entity for Sprints.  Just enable one of the custom entities, and rename it "Sprint".  We do that ourselves, which we'll outline further below.
Read more about enabling entities here


Create a Project to track development work

To start, you need a Project to contain all your Releases, Tickets, and Revisions (and Tools, Sprints, etc.).  Here at Shotgun, we make a project per Software project, but you can also make a single Project for all your development Projects.  A few of our clients have a "R&D" Project that they use to track all development.

Read more about creating Projects here.


Create a Tickets page in your Project

Now let's create a Ticket Page and put it inside our "Shotgun" Project. If you decide to organize your work into multiple Projects, create a Tickets page per Project.



Working with Tickets

Tickets come with some basic default fields:

  • Assigned To
  • Attachments
  • Description
  • Id
  • Priority
  • Project
  • Read/Unread
  • Related Tickets
  • Releases
  • Revisions
  • Status
  • Tags
  • Time
  • Title
  • Type

Let's take a look at a populated Ticket page to get a better feel for how we use each of these fields:



The Related Tickets, Releases, and Revisions fields are "multi-entity", meaning a Ticket can have many Related Tickets, be related to multiple Releases, and include many Revisions.



Let's now click onto a Ticket and look at its Detail Page to see all these fields in context of a Bug ticket:



The Ticket Detail Page has a configurable header and side panel, and then a threaded reply section where you can turn events on or off.  Here we see the first event, where Nephi Sanchez created the ticket, then we cut through to the end of the thread and see that Ben Willenbring changed the status to final then posted the results of the QA pass.


Auto-linking Related Tickets

One handy feature of Tickets, is that if you type prefix a Ticket reference with a "#" anywhere in the description or a reply, Shotgun will automatically create an entry for that ticket in the "Related Tickets" field.   The text will convert itself into a link to the ticket it references, and show its current status, and reciprocally create a link in the referenced Ticket's "Related Tickets" field a to the current ticket:





Auto-linking Revisions to Tickets

Similar to auto-linking related Tickets, adding a lowercase "r" in front of a Revision will automatically convert that text to a link, and create an entry in the "Revisions" field:




Working with Revisions

In Ticket #8131 we see two code Revisions that were checked in by the developers.  Let's click on one of them to take a closer look:



Our Revision Detail Page shows some meta data in a configurable header, and then we have a URL tab that has been integrated with Trac, our web-interface that we use with Subversion.  To accomplish this integration, we wrote a simple script using Shotgun's API to make the check-in process trigger the creation of a Revision in Shotgun and update all relevant meta-data.


We also configured a URL Tab called "Trac Details" that receives the Revision number ("code") as an argument so that we can access Trac from within our Revision Detail Page.  Here's what the tab's configuration looks like:




Now let's take a closer look at the Revision default fields:

Related Revisions
Revision Name
Related Revisions and Tickets are both multi-entity fields:  a Revision can have multiple Related Revisions and multiple Tickets.
Here's another look at these fields in action on a Revisions page grouped by day:


Now let's take a closer look at the Release entity type.  The default fields include:

Release Name


The Tickets field is multi-entity, so Releases can have multiple Tickets, as we see in this Releases page:

Let's click into a Release Detail Page and check it out:
Again we see that the top section has been configured to show some key meta-data, and then we have a whole bunch of tabs.  All of these tabs, except the Revisions tab, are Ticket tabs.  Each tab is filtering Tickets in various ways using their tags, statuses and other fields to show us what we want.  The Revisions tab, however is configured to show all the Revisions in the Release, by querying through the Revision's Ticket field to see which of those Tickets are linked to the Current Release:
We call this a "Deep Query" because we are traversing the connections through multiple Entities to figure out what we need.  Essentially this query examines each Revision's Tickets, and if any of them are linked to the Current Release, it shows them in the tab.

Now let's go through some customizations we've added here at Shotgun to enhance our process.  You will, of course, want to customize things your own way for your process.  Hopefully this will give you some good ideas.





At Shotgun, we wanted to organize our Tickets into Sprints, so we took one of the Custom Entities, enabled it, and called it "Sprint":





Our new Sprint entity came with the following fields:



Then we added some custom fields:

Expected Date
Velocity Notes
Here's a look at a Sprint page, sorted ascending by our Expected Date:
Notice that our each of our Releases may have multiple Sprints.
Now back on Tickets we added a custom field called "Sprint", of type "Entity" and restricted it to Sprints:
This allowed us to assign each Ticket to a Sprint:
So now we can group, filter, and sort our Tickets by Sprint.
To organize things a bit, we created a folder called Sprints, and a dedicated page for each one, and as we finish a release we archive its Sprints in a sub-folder (see the 1.9 sub-folder below):
Since we started working with Tickets, Releases, Revisions, and Sprints, we have created many custom fields and made extensive use of tags, and we continue to evolve the way we use Shotgun.  But to give you an idea, and without getting into too many more specifics, this is what our "Shotgun" project now looks like:
And of course, we have lots of pages inside each folder!

Related Documentation


Ask a question right here in the comments, create a new topic in our forum, or shoot us an email at  We're listening on all channels and will get right back to you.


Please sign in to leave a comment.