The Shortcut VCS integration offers several ways to associate Shortcut Stories with your VCS' feature branches or commits, as well as automated ways to change the workflow state of a Story as your work progresses. 

Working with Feature Branches

A Story is often analogous to the amount of work in a feature branch. To create a new feature branch, click the Story you want to work with, and then click the "Git Helpers" icon located in between the Story ID number and Settings ellipsis icon.

Then copy the suggested branch name to create and checkout a new branch for your story. Want to customize the suggested branch name? Set up your own with our GitHelper formatter.

Whenever you push a branch, it will be automatically linked to the story. 

Using a branch directive to create a new Story

If you don't yet have a Story for work you are doing, you can include "sc-new-story" in the branch name to have the Story created for you when you push the branch. For example, if you push a branch named "sc-new-story/fix-the-thing-that-is-broken", this will:

• Create a new Story in shortcut
• Name the Story "Fix the thing that is broken"
• Associate the branch with the Story
• Make you the requester & owner of the Story
• Put the Story in the first started state in your Workspace's default workflow

This feature does have a few limitations:

• The branch must not mention an existing Story using "sc-123"
• Your VCS provider identity must be linked to your Shortcut account. If changes
  you make in Shortcut via VCS show up in Story activity as being performed by "Somebody", your identity is not linked. In that case, look at these instructions.
• This creates the Story in the first started state in your Workspace's default workflow, and this currently cannot be configured

Associating Multiple Stories with a Single Pull Request 

Branches can be associated with multiple stories using pull request messages. Just add the Story numbers to the message with the prefix sc- in brackets.

While multiple Stories can be associated with a single branch, pushing to a branch with a different Story number will not disassociate it from any Story it was previously associated with. See the last section below on disassociating pull requests from Stories. 

Changing your Workflow State Using Event Handlers

You can use Shortcut Event Handlers to allow VCS events to trigger workflow state changes.

Opening a Pull Request from within Shortcut

When a Story has a linked branch, you can open a new Pull Request from the Shortcut UI by clicking the "Open PR" button next to the branch name. This will pre-fill the Story name in the PR name and the Story URL in the PR description.

Working with Pull Requests

When a Pull Request is opened on an already linked feature branch it will be indicated in the Stories associated with that feature branch.

It is also possible to associate a Story to a feature branch upon creation of a pull request or after a Pull Request has been opened.  

Add the bracketed text [sc-###] where ### is the Story number, or the Story URL

https://app.shortcut.com/{org}/story/{story-id}

 to a new Pull Request comment in your VCS provider:

This bracketed text or Story URL must be added as a comment on or in the description of the Pull Request. You can also put the bracketed text in the title of the Pull Request (Story URLs are not supported in the title).

The system supports sets of bracketed Story numbers on a Pull Request to associate multiple Stories at once:

If you're adding the Story URL, it needs to be the only text in the PR comment in order to be picked up:

Once Shortcut detects the PR and associates it with the Story, it will then comment back on the pull request with a link to the Story:

Overlapping Pull Requests

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

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

Prevent Pull Requests from moving a Story

To prevent a given PR from moving a story, do any of the following:

• Add a label named skip-sc to the PR
• Include the text [skip-sc] in the PR body
• Include the text [skip-sc] in the PR title

Note: The skip-sc functionality blocks any event handlers from taking action. Shortcut will still always move a story that it detects has open work to the very first started-type state in a workflow.

See Pull Request status

See the following statuses 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

See Pull Request Labels 

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

Disassociating Pull Requests from a Shortcut Story

Pull Requests can be removed from Shortcut Stories by clicking on the ellipsis icon next to the pull request within the Story and clicking either "Remove PR" or "Remove PR and Branch".

Moving Stories Back

The Shortcut GitHub integration is designed to only move your Stories forward, from unstarted to completed. As such, if you find you need to move a Story back to an earlier workflow state, you can do so in the Shortcut UI.

Updated January 18, 2024 15:43