Git the most out of the Shortcut VCS Integrations
BlogShortcut Best Practices
Shortcut Best Practices

Git the most out of the Shortcut VCS Integrations

Tiffany Go
Head of Product Marketing
July 1, 2023

Our VCS integrations are now even more integrated. Git ready, git excited, and git more done! Also, maybe git slightly annoyed at our overuse of the word Git in this blog post.

The workflow between GitHub, GitLab, Bitbucket, and Shortcut is now stronger than ever thanks to a:

  • Setup your preferred naming convention with customizable GitHelpers
  • Smarter controls with open work auto-detection
  • More control over drafts with Draft PR support
  • Better bidirectional syncing with GitHub Autolink Support
  • Tell a PR to skip updating it's associated Shortcut Story
  • Overlapping PRs
  • And even more!

Read on and/or watch the video below to learn what you can do with the Shortcut VCS Integrations. Do keep in mind that functionality does vary between the three VCE integrations.

Watch the video to see the new features (using GitHub as an example).

Set your preferred naming convention with customizable GitHelpers

Available with GitHub, GitLab and Bitbucket Integrations

If the default format from the Git Helper doesn’t match your own branch naming conventions, you can change it to whatever else you want. As long as the branch includes /sc###/ you’re good to go.

We've included a number of presets to choose from, but if you want to fully customize the formatting, select the Custom Format option at the bottom of this list of presets to select which attributes (and their order) should be part of the branch name.

Customize your Git branch formatting

You can also:

  • Auto-generate PR titles using the Product Area Field
  • Customize your VCS branch format with a Team’s mention name [team_mention_name]
  • Including the Epic name in the branch name for easy grouping of Epics in your VCS tool

Smarter controls with open work auto-detection

Available with GitHub, GitLab and Bitbucket Integrations

Our integration can now detect “open work” that’s associated with a Story when determining when to execute our “PR Opened” or “Branch Merged” event handler. If any open work exists, then the handler is not invoked.

What constitutes “open work”?

  • Another open Pull Request being associated with the Story other than the PR that is triggering the event. If you have multiple PRs associated with a Story, taking action with just one of them will not move the Story forward.  
  • A non-deleted, non-merged Branch other than the branch that led us to the Story from the event (this could be a branch that we found via the tree of merges (in which case it would be merged already) on a push event or the branch for a PR from a PR event.

More control with Draft PR support

Available with our GitHub and GitLab Integrations

If you open a pull request as a Draft in GitHub or as a WIP in GitLab, this will no longer trigger the Shortcut event handler to update the associated Story’s status. We’ll now recognize it as a draft and ignore it.

However, when you move it from a Draft / WIP PR to an Open PR, the Event Handler will trigger and update the Story.

Draft PRs do not trigger our event handlers

Better bidirectional syncing with GitHub Auto-link Support

Available with our GitHub Integration

Link a GitHub commit to a Shortcut Story by using [sc-xxx] in the title or body. This takes advantage of the GitHub autolink feature and so it needs to be initially configured within GitHub before you can put it to use.

Tell a PR to skip updating Shortcut

Available with GitHub, GitLab and Bitbucket Integrations

You can now stop a PR from updating or moving a Story. Simply write [skip-sc] in the title or the body of the PR or label the PR with skip-sc (this label option is not available in Bitbucket).

Writing [skip-sc] or labeling a PR as skip-sc will cause the PR to not update the Shortcut Story

Faster commands with associating commits via long URL

Available with GitHub, GitLab and Bitbucket Integrations

You can link a commit to a Story by entering the Story URL in the commit message.

Take advantage of information density and visibility in both platforms

See Pull Request labels in Shortcut

Available with GitHub and GitLab Integrations

Labels associated with pull requests are now displayed within Shortcut Stories. Hover over the PR within the Story pane to see them.

See status updates with enhanced Shortcut PR UI

Available with GitHub, GitLab and Bitbucket Integration

See the status of a Pull Request from right inside the Story pane:

  • Review required
  • Changes requested
  • Approved

And see the build status of a PR too:

  • In progress
  • Failed
  • Successful

More harmonious collaboration with Overlapping PRs

If you are working on a Story with a PR that overlaps with another PR, you'll be able to see it directly in a Story before you get to the merge stage so you can effectively collaborate with the right people to make sure there's no overlapping work. 


If you’re not already using this integration, what are you waiting for? Git to it! The VCS Integrations are easy to set up and make Shortcut a more helpful part of your workflow. Visit our Help Center to git started (you didn’t think we’d pass up one more chance to say “git” did you?) and learn how to set up any of our VCS integrations.

No items found.
Share this Shortcut story
Enjoy your work
Project management software should be helpful, not a hassle.