Shortcut

Learn how to connect your Shortcut workspace to Swarmia with an API token.

The Shortcut integration is currently in beta.

Swarmia connects to Shortcut with an API token. Once connected, your stories and epics sync automatically, so you can see them next to the commits and pull requests that delivered them.

A Shortcut API token is scoped to a single workspace, so the token you paste decides which workspace Swarmia syncs. There's nothing else to pick. Issue types and statuses map automatically.

Before you start

You need the admin role in Swarmia to connect an issue tracker.

Recommended: create the token with a service account

A Shortcut API token stops working when the member who created it is deactivated, and syncing stops with it. Create the token from a dedicated member account (for example, [e-mail]) so the connection doesn't depend on any one person.

Step 1: Create the API token in Shortcut

1. Open API tokens in your Shortcut account settings.

2. Name the token and give it permission to read all workspace data.

3. Copy the token before closing the dialog.

Step 2: Connect Shortcut in Swarmia

1. Go to issue tracker settings, click Connect, and choose Connect Shortcut.

2. Paste the token and click Connect.

Swarmia validates the token against Shortcut, stores it encrypted, and starts syncing. The first sync covers every epic in the workspace and the stories updated during the past year.

You can connect one Shortcut workspace per Swarmia organization.

Step 3: Assign Shortcut teams to Swarmia teams

Your Shortcut Teams sync to Swarmia, and you assign them to Swarmia teams in Settings → Team → Issues. Do this for every team: a team's Shortcut work shows up in Swarmia only after you've assigned it. Read more about issue ownership.

Linking pull requests to stories

Every Shortcut story and epic gets the issue key SC-<story id>, the same key Shortcut uses in the branch names it generates. Branches and pull requests that mention the key are linked to the story automatically. See linking pull requests to issues for all the ways Swarmia detects a link.

Keeping the data up to date

Swarmia keeps your Shortcut data in sync automatically — there's nothing to maintain. When you create or update a story or epic in Shortcut, the change shows up in Swarmia within an hour. Changes to your Shortcut Teams and workflows take a bit longer.

When the token stops working

If the token is revoked or its Shortcut account is deactivated, syncing stops and your Swarmia admins get an email about it. The workspace shows as Disconnected in issue tracker settings, where you can reconnect it with a new token.

The new token has to belong to the same Shortcut workspace. A token for a different workspace is rejected, because reconnecting rotates the token of an existing connection rather than creating a second one.

How do I disconnect Shortcut?

Contact us at [e-mail] and we'll disconnect the workspace for you.