Set up a Version Control System Integration

For instructions on setting up the Version Control System of your choice, please expand the one desired below:

github_128x128-5cd1461d5e.pngGitHub

With the Shortcut GitHub integration, specially formatted commit messages can be used to link stories to commits, branches and pull requests, as well as move stories across your workflow. Following these instructions, you can configure the Shortcut GitHub integration to work with one or more GitHub repositories.

 

Setting up the GitHub integration in Shortcut

mceclip0.png

  1. In the Shortcut app, click the User icon in the lower left corner, click Integrations, and then click GitHub.
  2. Click Add Account.

Setting up the integration in GitHub

 

Screen_Recording_2022-01-21_at_08.33.50.46_AM.gif

After clicking Add Account in Shortcut, you will be taken to GitHub to select which GitHub account to link. From this next screen, you can authorize access to all repositories in the account, or only select repositories.

Successful installation of our integration requires the user performing this action to be an Admin in both Shortcut and GitHub. Additionally, while the GitHub integration will connect to multiple Workspaces, it will only connect with one Organization at a time.

Once all or the select repos have been selected, click Install. You will be redirected back to Shortcut to this message:

mceclip1.png

 

Connecting Individual Accounts

Individuals will need to ensure that their primary email address in GitHub is the same as one of their email addresses in Shortcut. In GitHub, check your personal account settings, under the email tab.


GitHub_Primary_Email_Address.png
If this is not the same email address used to create your Shortcut account, you'll need to add that email address to Shortcut.

GitHub Event Handlers

To set up your integration to use our Event Handlers, follow these instructions. When you're done, make sure to check out our guide to using our VCS integration with PRs and Branches.

gitlab_128x128-ffcad866a5.pngGitLab

With the Shortcut GitLab integration you can link Stories to commits, branches and pull requests, as well as move Stories across your workflow. Following these instructions, you can configure the Shortcut GitLab integration to work with your GitLab account.
Note: This integrates with GitLab.com and self-managed GitLab installations using version 9.5 or higher.
For self-managed GitLab users: Our GitLab integration needs to talk to the API of your self-managed GitLab install to properly process some event payloads. It determines the address of the API using the URLs included in the webhook payloads, and that address needs to be publicly accessible for us to reach it. Non-resolvable hostnames will cause the integration to not work correctly.

 

Setting up the integration in Shortcut

Only Admins and Owners can activate this integration in Shortcut. In the Shortcut app, click the Integrations option in the lower left corner of the UI, and then click GitLab. Click the Slider to enable, then copy the GitLab Payload URL and open your GitLab account.

In GitLab, choose specific Projects that you want to send data to Shortcut, or if your GitLab.com plan supports Group Webhooks, you can send data from every Project in the Group. From the Project page (or Group page), click Settings >Webhooks, then paste the GitLab Payload URL into the Integrations URL field.
Next, check that the correct events will be sent to Shortcut. Click the checkbox for:
  • Push Events
  • Comments
  • Merge request events
You may optionally include Confidential Comments.
If you are not using GitLab's Group webhooks, be sure that you've added the GitLab Payload URL to the Webhook Settings for each Project that should send data to Shortcut. Add user(s) email address as public in GitLab in order for Shortcut's event handler to determine which GitLab user performed certain actions in Shortcut, we match the email from GitLab payload to that of the Shortcut user. Ensure that the public email in Settings (click on the user icon options) > Edit Profile is set to the appropriate email for the user in Shortcut.

Access Token

The last step is to place a personal access token from GitLab into Shortcut. You may use an individual user's token, but it is recommended that you create a bot user in GitLab. 

 

1. Create a new user on your GitLab.com organization. Consider using a name that signifies this user connects GitLab to Shortcut, like 'Shortcut Bot'.

2. In GitLab, invite your bot user to the Projects that you want Shortcut to access, and grant that user Developer permissions.

3. Log in with the bot user account and open the User Settings.

4. Generate a personal access token scoped to have API access  

 

 

5. Copy the personal access token and paste it into the API Access Token field in the GitLab integration pane. Click Update API Access Token to save the token value.

 

GitLab Event Handlers

To set up your integration to use our GitHub Event Handlers, follow these instructions. When you're done, make sure to check out our the guide to using our VCS integration with PRs and Branches.

bitbucket_128x128-2fcc9012d1.png BitBucket

With the Shortcut Bitbucket integration, you can link Stories to commits, branches and pull requests, as well as move Stories across your workflow. Following these instructions, you can configure the Shortcut Bitbucket integration to work with your Bitbucket Cloud account.
Note: This integrates with Bitbucket Cloud and not Bitbucket Server.

 

Setting up the integration in Shortcut

Only Admins and Owners can activate this integration in Shortcut. In the Shortcut app, click the Gear icon in the upper right corner, click Integrations, and then click Bitbucket. Click the Slider to enable, then click Connect to Bitbucket.

image-0.png

Next, authorize the Bitbucket account you would like to connect to this Shortcut Workspace.
Note: You can connect multiple Shortcut Workspaces to the same Bitbucket account, but you cannot connect multiple Bitbucket accounts to the same Shortcut Workspace.
image-1.png
When you’ve successfully authorized Shortcut to access your Bitbucket account you’ll see which Bitbucket account Shortcut is connected to in the integrations screen.

image-2.png

BitBucket Event Handlers

To set up your integration to use our BitBucket Event Handlers, follow these instructions. When you're done, make sure to check out our the guide to using our VCS integration with PRs and Branches.

Updated

Was this article helpful?

2 out of 3 found this helpful

Have more questions? Submit a request