# GitHub

Connect Shortcut with GitHub to link Stories to commits, branches, and pull requests, and automate workflow state changes.

The GitHub integration links Shortcut Stories to commits, branches, and pull requests so development activity stays visible alongside the work.

**Multiple Workspaces?** Simply open the GitHub page from the Integrations window and select **Add Account from Another Workspace**.

## Install the GitHub Integration

Only GitHub and Shortcut Admins can install the integration.

1. In Shortcut, open **Integrations > GitHub**.
2. Select **Add Account**.

![GitHub integration settings in Shortcut](/help/assets/vcs-github-shortcut-settings.png)

3. In GitHub, choose the account or organization to connect.
4. Grant access to all repositories or select individual repositories.
5. Select **Install**.

![Select GitHub repository access](/help/assets/vcs-github-repository-access.gif)

Shortcut returns to the integration page and displays the connected account.

![A connected GitHub account in Shortcut](/help/assets/vcs-github-connected-account.png)

## Connect Individual Accounts

Shortcut matches GitHub activity to members by email address. Each person should make sure their primary GitHub email matches one of the email addresses in their [Shortcut profile](/help/account/profile-settings).

![GitHub primary email setting](/help/assets/vcs-github-email.png)

## Using VCS Integrations

The following behavior applies to GitHub, [GitLab](/help/integrations/gitlab), and [Bitbucket Cloud](/help/integrations/bitbucket), except where noted.

### Associate a Branch with a Story

Open a Story and use **Git Helpers** to copy its suggested branch name. The branch contains `/sc-<story-id>/`; when it is pushed, Shortcut associates it with the Story.

You can customize the Git Helper branch format from **Integrations > your VCS provider > Git Branch Formatting**. Keep `/sc-<story-id>/` somewhere in the format so Shortcut can identify the Story.

You can also associate work by adding `[sc-123]` or the full Story URL to a branch, commit message, pull request title, pull request description, or pull request comment.

### Commits

For a direct commit or hot fix, include `[sc-123]` or the Story URL in the commit message. Multiple references such as `[sc-123][sc-456]` associate the commit with multiple Stories.

Commit verbs configured in your Workflow can move a Story forward. For example, a commit containing your Workspace's finish verb and `[sc-123]` can move Story 123 to a completed state.

Commits can be removed from a Story from its Activity section and restored later.

### Branches and Pull Requests

When a pull request is opened from a linked branch, Shortcut displays it on the associated Story. You can also link an existing pull request by adding `[sc-123]` to its title, description, or a new comment.

Use `[sc-new-story]` in a pull request title, description, or comment to create and associate a new Story. A branch containing `sc-new-story` can do the same when pushed.

Draft GitHub pull requests and GitLab WIP merge requests do not trigger event handlers until they become open. Add the `skip-sc` label, or include `[skip-sc]` in the pull request title or body, to prevent its event handlers from moving a Story.

### Event Handlers

Event Handlers move linked Stories to selected Workflow States when development events occur.

1. Open **Integrations > your VCS provider > Event Handlers**.
2. Select **Add New Event Handler**.
3. Choose an event, such as a branch association, commit association, pull request opening, approval, label, review request, or merge.
4. Enter the relevant branch or label when requested.
5. Select the destination Workflow State and save.

![Configure VCS Event Handlers](/help/assets/vcs_event_handlers.gif)

Pull request labels are not available for Bitbucket Cloud, and pull request review-requested events are not available for GitLab.

If a Story has another open pull request or an unmerged branch, Shortcut can treat that as pending work and delay a pull-request-opened or branch-merged handler.

## GitHub Enterprise

Before setup, [contact Shortcut Support](/contact) to enable GitHub Enterprise for your Workspace.

1. In Shortcut, open **Integrations > GitHub**, select **Add Account**, and connect GitHub.
2. Enable **GitHub Enterprise** and copy the **GitHub Enterprise Payload URL**.
3. In the GitHub repository or organization, open **Settings > Webhooks > Add webhook**.
4. Paste the Payload URL, set the content type to `application/json`, select **Send me everything**, and add the webhook.

If selecting individual events instead, enable **Create**, **Delete**, **Comment**, **Pull Request**, and **Push**. Each member's primary GitHub email must also match an email in their Shortcut profile.