Tracking Time on GitHub PRs Using Shoutbase & Zapier

I’m a growth-minded, efficiency enthusiast. What does that mean? I strive to learn and grow, usually with a focus on being more efficient with my time and energy. I’m not perfect, but I strive to continue on that path, iterating on my process, and improving each week. An important part of these iterations is collecting data about where I’m at now, so I can understand where I want to go.

As a software engineer, one of the best metrics I collect is how much time I spend completing a specific coding task. Like many developers, GitHub is my tool of choice for tracking code changes. However, GitHub doesn’t include any time tracking capabilities. That’s where Shoutbase comes in. Shoutbase is a quick and easy (dare I say, efficient) service for managing time records for teams and individuals.

Thanks to an awesome tool called Zapier, it’s easy to connect my Shoutbase and GitHub accounts, so they can automatically communicate back and forth in ways that I define. With these “Zaps,” I can transfer data from one system to the other without having to perform any additional, manual steps that would throttle my workflow. In isolation, GitHub and Shoutbase provide me with value, but integrated together through Zapier, they provide so much more. The GitHub + Shoutbase + Zapier webapp trio gets my efficiency enthusiast stamp of approval. Go team!

I have a number of Zaps that connect my different webapp accounts, including Shoutbase, GitHub, Jira, and beyond. They all do different tasks to help me track data, automate menial tasks, and overall save me time and mental energy. In the remainder of this article, I want to highlight one simple Shoutbase + GitHub Zap that will help you get started with defining an integration that helps you work better.

At the end of this step-by-step guide, you will be able to link GitHub pull requests to Shoutbase time entries. When a new time entry is created or stopped in Shoutbase, the GitHub pull request will be updated with a comment, including the description of the time entry and the duration. Later, you’ll be able to go back to your pull request and see exactly how much time it took you to complete the task. You can then use that data for your own personal growth journey or to communicate your time-spent with your manager or a client.

Getting Started

Before creating this integration, make sure you have the following accounts set up and a basic understanding of the systems we’ll be working with. If you’re new to one or more of the technologies listed, I’ll include information about getting started with each.

Shoutbase

Shoutbase is a time tracking system built for speed and simplicity. It’s optimized for fast data entry that lets you record time quickly, so you can get back to what you’re doing with minimal disruption. Shoutbase is free for individual users, and setting up an account is a breeze.

GitHub

GitHub is a popular development platform that helps manage code changes and version control. If you’re new to the world of git, sign up for a GitHub account here, and take a minute to learn the basics.

Zapier

Zapier is a tool that helps you integrate the different web applications you use, helping you save time and energy. Zapier also includes a free trial and a free tier. If you are brand new to Zapier, check out their Getting Started Guide to gain a basic understanding of using Zapier and creating “Zaps” before continuing with this tutorial.

Technical Design

Before jumping into creating the Zap, here is a brief technical design of how our integration will work:

1. User creates time entry in Shoutbase. This is our “Trigger,” which means this event will cause Zapier to run the processes we define in our Zap.
2. Zapier polls Shoutbase for new time entries by the user. Every 5–15 minutes, Zapier will make another request to Shoutbase to fetch entries.
3. Shoutbase responds with a set of time entries.
4. From the time entries response, Zapier determines if there are any new time entries since the last time it made a request. If there are no new time entries, nothing happens, and Zapier resets to make the request again in 5–15 minutes. If there is a new time entry, Zapier continues to the next step.
5. When a new time entry is found, Zapier runs custom javascript code, which we will define. The code will determine whether to post a comment to Github, and then format the data appropriately.
6. Once the code is finished running, Zapier uses the data from the previous step to call the GitHub API to insert a comment in the proper pull request.

The following uml diagram illustrates how information is requested, transformed, and passed through the integration system.

Create a New Zap

Log into your Zapier account. Once logged in, click “My Zaps.” Here you will see your Zap dashboard. This is where you can see and control the Zaps you’ve created in the past or create a new Zap. Click the “Make a Zap!” button.

Trigger Definition

The first step to creating a Zap is defining your trigger. A trigger is an action that occurs in one system that causes something to happen in another system. In our case, “Shoutbase New Time Entry” will be the trigger.

1. Name Your Zap

I like to name Zaps very explicitly, so I can easily know what my triggers and actions are just by reading the name. In this case, I’m naming my Zap “New Shoutbase Time Record => GitHub PR Comment.” You can use this or choose something different.

2. Choose Triggering App: Shoutbase

The Shoutbase Zapier integration is new and currently in beta version. You’ll have to use this invitation link to select Shoutbase as your triggering app. In the future, you’ll be able to select Shoutbase from the list of other applications.
https://zapier.com/developer/public-invite/31432/fa70581019fd453aed7317c47eb43d99/

3. Select Trigger Event: New Time Entry

From the dropdown menu, select “New Time Entry.” This is a polling trigger event, which means the Zapier API will make regular requests (every 5–15 minutes) to check if there are any new time entries for your Shoutbase account. When there are, it will continue to the next step.

4. Connect Your Account

Continue to connect your Shoutbase account. A window will appear requesting access to your Shoutbase account. Authorize Zapier to connect to your Shoutbase account by clicking the “Allow” button. If you do not have a Shoutbase account yet, go to shoutbase.com to register and verify your account.

5. Finish Trigger

In the “Customize Time Entry” section, skip this for now by clicking “Continue.” Next is the “Find Data” section. Here, Zapier will poll the Shoutbase API for recent time entries to give you an idea of the data you’ll be working with for the rest of the Zap.

If you are new to Shoutbase and haven’t created a time entry yet, now is a great time. Log into your Shoutbase Account. In Shoutbase, create and save a time entry that includes a link to a GitHub pull request (PR) in the description, as well as a start and stop time.

Once you’ve created this time entry in Shoutbase, go back to Zapier. Click the “Test & Continue” button. This will poll for new time entries. Select the time entry you just created. And that’s it for the trigger!

Format Data

Next, we need to format the data from our trigger into something our action can use. In this case, we want to capture the GitHub PR number and parse the duration from the time record.

1. Code by Zapier

From the menu, select “Code by Zapier” and choose “Run Javascript” as your event.

2. Input Data

Add the data from the previous steps, which we will use in our custom code. Add the duration and description from Step 1 (time record).

3. Code

Add javascript for formatting duration and extracting GitHub PR number. In the following example, I split the description by a string found in GitHub PR URLs and extracted the string immediately following /pull/. That is the GitHub PR number. You can write fancier code that can accommodate multiple GitHub URLs. For me, that’s not necessary.

I also have some generic code that formats the time record duration from seconds into hours, minutes, and seconds, so it’s easier for me to read later.

Copy the code below, hosted by GitHub Gist.

4. Finish Code Step

Test your code and continue. If you get an error when running your test, double check that the time record you selected as “Test Data” in Step 1 includes a GitHub PR URL. If it does not include a URL, go back to the Trigger definition (1. New time entry in Shoutbase) > Find Data, and find and select an item that does include a GitHub PR URL. Then rerun your test. Also note, you must have the proper permissions on your GitHub account to comment on certain pull requests. Make sure you have the proper credentials if you continue to have issues.

Filter Definition

If the time record does not contain a GitHub PR, we will want Zapier to filter out this time record and not continue on with the rest of this Zap. Therefore, we need to add a Filter step.

1. Choose App and Event

Select “Filter by Zapier” from the App dropdown menu.

2. Define Filter

In the “Continue only if…” options, select “Pr ID” nested under “Run Javascript,” then choose “Exists.” Add another condition for “Repo” and choose “Exists.” If the Pull Request ID or Repo doesn’t exist or is null, the Zap will discontinue at this point. If both contain data, the Zap will continue to the Action step.

Action Definition

1. Add GitHub Action

Select GitHub as the App and “Create Comment” as the Action Event. Connect your GitHub account in the authorization popup window.

2. Select GitHub Repo

The GitHub repository will be dynamic based on the link you pasted in the Shoutbase time entry. For Repo, scroll to the bottom of the options and select “Use A Custom Value (advanced).”

In the “Custom Value for Repo Full Name” field, click the dropdown menu. Click to expand “2. Run Javascript.” Select “Repo.” This is capturing the “repo” parameter we defined as output in Step 2.

3. Add Comment

Here you can customize the comment to suit your needs. I like to include the entire description from my Shoutbase time entry, as well as the duration we formatted in Step 2. This way, I can read the comment, get a full context of what I was working on, and see how long I worked, all in a readable format.

4. Select GitHub PR

Like the GitHub repository, the pull request number is also dynamic based on the URL in the Shoutbase time record. Therefore, we’ll select “Use a Custom Value” and the PR ID parameter from Step 2 to define the pull request number.

5. Finish Up

Click the “Continue” button. Run your test. After receiving a success message in Zapier, check your GitHub pull request (the one you linked in the time record at the beginning of this guide). You should see a comment appear. It works!

Finally, don’t forget to turn on your Zap. This is done by toggling the grey switch at the top of the screen to “On.” When your Zap is on, Zapier will continuously poll your Shoutbase account for new time records. If it’s off, the Zap won’t work.

See Your Zap in Action

1. Enter Time in Shoutbase

Now that your Zap has been created and activated, let’s see it in action. Log into Shoutbase and select “New Entry” from the nav menu. (If you’re using mobile Shoutbase, you can click the blue plus button at the bottom of the screen.) Paste a GitHub pull request URL into the time entry description, along with any other details. Add a start and stop time. Zapier only polls the Shoutbase API for stopped timers, so if you don’t include an end time to the time entry, Zapier will not recognize it until it is stopped.

2. Manually Run Your Zap in Zapier

Zapier polls the Shoutbase API for new time entries every 5–15 minutes, so you won’t instantaneously see your new time record appear as a comment in GitHub. However, you can manually trigger Zapier to run your Zap and check for new time entries instantly. To do this, go to your Zaps dashboard in Zapier, find your Shoutbase/GitHub Zap, click the dropdown menu, and click “Run.”

3. GitHub PR Comments

Log into your GitHub account, open the PR linked in the time entry description, and see the new comment. Do you smell that? That’s the smell of precious data automatically transmitted from one system to another!

Conclusion

This simple Zap took only minutes to put together, and it performs a task that would otherwise disrupt my workflow, waste valuable time, and lead to less precision in my time tracking data. And it’s only just the beginning. The possibilities for integration and optimization are endless. Zapier lets me expand the capabilities of web applications I prefer interfacing with and minimizes time wasted on tedious tasks.

I enjoy tracking time in Shoutbase because it’s fast and easy to use, and it conveniently manages the time for my entire team with tags, goals, and reports. Now with integrations through Zapier, Shoutbase helps tools like GitHub add even more value to my workflow. And Shoutbase is actively expanding its capabilities to integrate with other software-focused systems like Jira, GitHub, and Slack, as well as billing systems like Harvest and Quickbooks. Stay tuned to see Shoutbase’s integration capacity grow, and get creative with your own integrations!

If you’re interested in learning more, check out my other articles about why and how integrations can make us all better at doing what we do.

Better Time Tracking for Jira Using Shoutbase & Zapier

Dynamic Duos: Integrating Jira & Shoutbase Using Zapier

Automated Time Tracking and Billing Integration with Shoutbase & Quickbooks

What did we miss?

Please let us know by tweeting to @shoutbase on Twitter.

Stormi Hoebelheinrich

Developer of Shoutbase and Olio Apps.

LinkedIn: @shoebelheinrich

Thanks for reading!

If you would like to learn more about Shoutbase, please follow us on Twitter, Instagram, Facebook, LinkedIn, or Medium!

Originally published at https://www.shoutbase.com on October 31, 2019.