Emulating A Ticket Management System Using GitHub Issues, Milestones, & Projects

The TL;DR

In this article you will:

• Read about the underlying motivation for why I decided I wanted to emulate an enterprise grade ticket management system like Jira, Salesforce, and ServiceNow in my own projects
• Learn what benefits I was hoping to gain from the experience of instituting such a system in my personal / portfolio work
• Follow a step-by-step guide duplicating my work so that you can use the same system on your own personal / portfolio projects, reaping the same benefits

The Premise

As a Technical Support / Solutions Engineer working towards becoming a Software Engineer I'd like to lend my portfolio projects a little more credence ideally through two asynchronous efforts:

1. Running the projects as though I were a full-time Software Engineer (i.e. standup, sprint planning, etc.)
2. Performing periodic - and final, upon project completion - data analysis with the gathered metrics to see how I stacked up

The idea behind this is that it will give me more "bullet points with meaningful numbers" to include on my resume when applying to jobs, as well as interview talking points that I can use to show how effective I would be in a low-to-mid level Software Engineering role, while having the helpful side-effects of making me a stronger Engineer.

The Hurdle

While GitHub Issues, Milestones, and Projects are powerful individually, the pieces are disparate (i.e. there's no predefined, "out-of-the-box" method to emulate the ticketing systems I'm familiar with after having worked for almost 3 years in a professional setting). I wanted a tool that was reminiscent of the "Epics" that I loved to track "Feature" work in my projects that would also allow me to later grab and analyze the data - either raw through the API or another means.

"Epics"?! What The Heck Is An "Epic"?!

TL;DR... An "Epic" (or "Epics") represent a large and overarching feature or project, providing high-level descriptions of what needs to be accomplished to deliver that particular feature / project.

More Details: In the context of ticket management within software engineering and sprint planning, the term "Epic" refers to a large and high-level user story or work item that represents a significant feature or piece of functionality. Epics are used to group related tasks and user stories together under a common theme or goal. They are typically too large and complex to be completed in a single sprint or iteration and need to be broken down into smaller, more manageable units of work called "user stories" or "tasks."

At my core, I wanted...

• To emulate a system I knew really well (and would eventually tweak) to give me insight into the data that would make me a better developer - one who could accurately estimate, meet deadlines quicker, and was able to effectively work within a system akin to one found in a professional setting;
• To be able to showcase the numbers / data on my resume and have verifiable proof of that data that I could show to prospective employers.

Finally, I wanted to centralize this within GitHub to the best of my ability. I didn't want to require a third-party plugin or have yet another website that I had to configure to gain access to this data. Further, I wanted this data on a repo-by-repo basis where I could click a link and see, at a glance, how I was doing on the project overall, with the potential for dashboarding either baked into GitHub or the ability to access the data via API to build my own external dashboard to include in the final project's deployment.

The Execution

What I was able to come up with was a suitable "first draft" that gave me the kind of access and insight I was looking for and would allow me to do the kind of data analysis I wanted to accomplish at later (regular) intervals in the project. Thankfully, no major external configuration was required to accomplish this task - all it really took was a touch of creative thinking, a generous helping of "reading the docs", and a dash of elbow grease to accomplish v1.0.0.

Preview of the End Results

Setting Up Our "Epic" Label

1. Assuming you haven't already done so, create some larger issues - those that would be considered "Epics" - by clicking the green "New Issue" button in your repo. No need to include anything in the body of these "Epics" yet - that will come into play shortly.

   

2. Click the "Labels" button and you'll be directed to a new screen.

   

3. After clicking the "New Label" button (1) enter the details of the new "Epic" label you're creating for your project. You can keep it simple with your label name or go fancy, add a description if you like, and randomly generate a color for the label (2) (I recommend going for something that's eye-catching). Once satisfied click the "Create Label" button (3).

   

4. Return to the "Issues" screen. Click the "Select All" checkbox (1), followed by the "Labels" dropdown (2), and select your new "Epic" label (3). Click out of the "Labels" drop down and your label will be applied.

   

Setting Up Our "Milestones"

1. Click the "Milestones" button and you'll be redirected to a new screen

   

2. Click either the "New Milestone" or the "Create a Milestone" button to be directed to the form to create a new "Milestone".

   

   Quick Note!
   Unlike with the "Epic" label where we created it once and then we're done, we're going to create one "Milestone" per "Epic" correlating them in a 1:1 relationship. So, in our example, we're going to create a "Scaffold Frontend" Milestone and a "Scaffold Backend" Milestone.

3. Enter a name for the "Milestone" that you're creating (optionally include a "Due Date" and a "Description"). Once you're satisfied, click the green "Create milestone" button.

   

4. Repeat Steps 2 & 3 in this section, creating one "Milestone" per "Epic" ticket you instantiated at the start. Once done, your "Milestones" screen should look something like this, at which point you can return to the "Issues" screen.

   

Assigning "Milestones" To Our "Epics"

1. Click the checkbox next to a single "Epic" (1). From the "Milestone" dropdown (2), select the appropriate "Milestone" that should be assigned to that "Epic" (3). Once clicked, the "Epic" will now be assigned to that particular "Milestone".

   

2. Repeat the previous step until all of your "Epics" have been assigned to their appropriate "Milestones". Once completed, you should see a little "Milestone" icon underneath the title of each of your "Epics".

   

Creating "Task" Issues / Tickets

1. Create a few new "Task" issues / tickets, making sure to assign each ticket to a relevant "Milestone". Afterwards, your "Issues" page might look something like this:

   

(OPTIONAL): Listing "Task" Issues / Tickets As A "Task List" In An "Epic" Issue / Ticket

1. Open an "Epic" ticket, clicking the ellipsis (...) icon in the top-right corner of your original description (1) and select "Edit" from the drop down (2).

   

2. In the "Edit" bar, click the "Add a task list" icon (once clicked, a - [ ] will appear in the Body text box).

   

3. Next to each - [ ] symbol in the "Description" body, type the # key and select the Issue / Ticket number you would like to list as a "Task" to complete as part of the Epic.

   

4. Once you've created your completed "Task List" click the green "Update comment" button in the lower right hand corner of the "Description" section.

   

5. Repeat Steps 1-4 for all of your "Epic" tickets. Once complete, you should see a little checklist icon providing you with a total number of items for each "Epic" checklist.

   

Creating A Project

1. Click on the "Projects" link at the top of your screen.

   

2. Once you've been redirected to the "Projects" screen, click the green down arrow next to the "Link a project" button (1) and select "New Project" from the dropdown (2). The "Link a project" button name will change to "New project". Click the "New project" button.

   

3. A prompt window will appear on your screen asking you to select the type of "Project" template you're looking to create (1) and to change the name of the "Project" (2). In this walkthrough we're going to stick with "Table" as our template. Once you've made your selection and changed your name, click the green "Create" button at the bottom right-hand corner of the prompt window (3).

   

4. Your table will appear on your screen but it will be empty. You'll be prompted to either type in a new issue or to "Add item from repository". Select "Add item from repository" and a window will open on the right-hand side of your screen.

   

5. From the dropdown (1) you'll have the ability to select which issues from specific repositories you want to include in this project. As we're creating a 1:1 (project to repo) relationship, select the repo you've been working in from that dropdown. Click the "Select All" checkbox (2) and then click the green "Add selected items" button in the bottom right-hand corner of the side window (3). Close the side window once complete.

   

6. Click the + icon in the header row of your table (1) so we can add two columns. Click the checkbox next to "Labels" (2) & "Milestone" (3), then click out of the dropdown menu. You should now see columns for both of those fields.

   

7. Click the down arrow next to your "View" tab (1) and select "Group by:" (2).

   

8. A dropdown of options will appear on the screen - select "Milestone" from the dropdown.

   

Now we have our end result which gives us an "at-a-glance" view of specific tickets / issues that are related to an overall feature.

Of course there are other features and data points that we can add here:

• Workflows to move tickets from one state to another based on whether a branch or pull request was created
• Fields related to time estimates (aka "story points"), linked pull requests, linked branches, etc.
• Remove and organize fields / columns so the view matches what makes the most sense for our specific needs
• ...and more!

The Takeaway(s)

Ultimately I believe that this will work for my purposes, at least for now. While it's not exactly what I was looking for, it's a suitable alternative that gives me the kind of visibility I want and will hopefully make future dashboarding easier - either directly from within GitHub or through an external one that I create.

As I find other configurations / measurements / workflows / options that could be helpful I'll include them as supplementary articles. If you found this helpful, or have any constructive feedback, please feel free to share it in the comments below. Thanks for reading!