Tracking deploys with Shortcut and GitHub

Part of what we’re trying to do at Shortcut is automate your entire software development workflow.

This is worth doing for a number of reasons. For project managers, automated state changes means your data is more accurate, which means Shortcut will be better at providing guidance around how much your team will be able to get done.

And for developers, automation means moving faster — one less repetitive task means more time to focus on real work. This is important because the more overhead there is to a continuous process, the more likely that process will eventually fail.

Automating this workflow as shown reduces the number of manual steps by 50%

While building first-class support for deploys is on our roadmap, it’s already possible to automate moving a story to a workflow state such as “Deployed”, and comment on which deploy it went out in, using the Shortcut API.

It’s been helpful for us to know what was deployed and when, and it’s especially helpful to know it was deployed at that moment, not whenever the developer got around to moving the story, which might be a couple hours or even days later. And linking to the GitHub comparison page means we can quickly and easily see what code changes were included in the deploy.

An actual automated deploy message in a Shortcut Story

Let’s walk through how to automatically track both manual and continuous deployments.

How to Track Manual Deployments

Format your Branches & Commits.

To associate your GitHub work with your Shortcut stories, you include the story ID in your branch name, or if you’re working directly on the master branch, in individual commit messages. There’s a lot more you can do, but I’ll leave that to our GitHub integration guide.

Merging the “ac/ch123/my-story-name” branch as a Pull Request in GitHub will helpfully include the name of the branch in the merge commit message, which is what we’re looking for.

Get the Commits from the Current Deploy.

If you can get the range of commits between the last and current deploy (how exactly depends on your deploy process), the following shell script will extract your story IDs from that range of commits. This is just for demonstration — the final code below will handle this step for you.

Update the Stories.

Once you have the story IDs for the deploy, it’s a simple matter of updating them using the Shortcut API. There are many ways to go about marking a story as deployed, but at Shortcut we’re moving the story to a “Deployed” workflow state, and posting a comment with details about the deploy.

How to Track Continuous Deployments

Several CI/PaaS companies such as Circle CI, Travis CI, and Heroku allow you to automatically kick off a deploy just by merging a branch. To automatically track this type of deploy in Shortcut, you could configure your Shortcut GitHub integration to move a story to “Deployed” when an associated branch has been merged to the “deploy” branch. You could even support separate staging and production environments:

An example GitHub configuration in Shortcut to track continuous deployments

Show me the Code!

The source code from this article is available here. It’s very close to what we use internally at Shortcut for tracking front-end deploys, but feel free to modify and use it however you or your team sees fit. If you have any comments, suggestions or feedback, please let us know.

Cheers! 🍻

‍