Automate Shortcut Story Status from GitHub Pull Requests
Shortcut Event Handlers move linked Stories to chosen workflow states when GitHub events occur. Configure the event and destination state after installing the integration.
GitHub and Shortcut administrators install the integration. Members should match their primary GitHub email to an email in Shortcut; only granted repositories participate.
Example: move a linked Story to In Review when its pull request opens, then use a separate merge handler for the completed state after validating your team’s release policy.
Step-by-step guide
Verify the repository connection
Open Integrations > GitHub and confirm the correct account and repository access. Have an administrator install or adjust the GitHub App if the repository is missing.
Link one Story to its pull request
Use Git Helpers on a Story to generate a branch containing /sc-<story-id>/, or add [sc-123] with the actual ID to the pull request title or description.
Create the event handler
Open Integrations > GitHub > Event Handlers and select Add New Event Handler. Choose the pull-request event, any requested branch or label condition, and the destination workflow state.
Exercise the intended transition
Use a harmless linked test Story and open the relevant pull request. Inspect the Story’s new state before enabling a merge-to-completed policy for production delivery.
Common mistakes
Testing with a draft pull request
Draft GitHub pull requests do not trigger handlers until opened. The skip-sc label or [skip-sc] text can also intentionally suppress transitions.
Sources and verification
Based on product documentation checked on 2026-11-04. This is a documentation-based guide, not a hands-on benchmark. Features and availability can change.