A REPL environment and Rake tasks to synchronize Shortcut and Google Sheets to enhance Shortcut's capabilities and facilitate low-friction planning.
- REPL with ActiveRecord-esque models for interacting with Shortcut & Sheets
- Bi-directional sync between Shortcut Epics and Google Sheets
- Automatic creation of canonically named Bi-Monthly Iterations
- Prioritization of iteration "Ready" stories based on epic sort order, priority, product area, blocked status, due date, etc.
- Template-based Shortcut Epic creation for things like Monthly Chores
- Local Sinatra-based OAuth2 authorize endpoints to create Google OAuth Access Tokens 🐐
- Bulk creation of stories from CSV
- Migrate deprecated "Project" field values to Custom Field values
Automatically move all incomplete stories from the previous iteration to the current iteration🎉 Now supported natively in Shortcut
This project provides customization and automation that sits on top of Shortcut to provide a more flexible and powerful planning experience. Google Sheets is familiar and flexible. A central "planning sheet" can then be a staging area to prioritize and organize initiatives before they're pushed into Shortcut.
Rather than needing to think in target dates, we've found it helpful to think in target iterations. Our planning sheet automatically translates canonical iteration names with start/end dates, so we can plan talking about iterations, then push the resulting dates into Shortcut epics.
When we consider a new initiative, it usually starts as a "Scoping" story in Shortcut. That story represents discovery and definition of the initiative. After scoping is complete, we'll make a go/no-go decision. If we decide not to proceed right now, having an Epic sitting in the hopper is confusing. So, the Sheet view allows us to prioritize Epics alongside Stories. The Sheet order can then be pushed into Shortcut.
Using Google Sheet's column filtering criteria is more intuitive for those less familiar with Shortcut.
$ rake -T
rake config:check # Check config is valid
rake config:export # Export the config.yml file as a base64 encoded string
rake monthly_chores:create_current # Create the next monthly chores epic
rake monthly_chores:create_next # Create the next monthly chores epic
rake planning:prioritize_shortcut # Sort epics by sheet order and ready stories by priority
rake planning:review # Interactively review any out-of-sync initiatives and choose whether to update shortcut or the sheet
rake planning:update_sheet # Fetch information from shortcut and update the sheet with it
rake shortcut:iteration:create_next # Create the next iteration
rake shortcut:project_sync:run # Ensure that all stories with a project have the correct product area set
Once you've got everything configured in config.yml, run rake config:export to produce a base64'd version suitable to drop into ENV to trigger actions via GitHub Actions or another crotab-like provider.
asdf plugin add ruby
asdf install
gem install bundler
bundleSee config.yml.example
Set shortcut-api-token in config.yml or SHORTCUT_API_TOKEN in .env.
- Generate an OAuth2 Client at https://console.cloud.google.com/apis/credentials with the required scopes and permissions to access the Drive and Sheets APIs.
- Download its JSON config to
client_secrets.json. - Run
make serveand visit http://localhost:4567 to fetch access and refresh tokens, saving them togoogle_credentials.json. - The refresh token will then automatically be used to refresh your credentials as necessary.
Tab completion for rake is really handy.
brew install bash bash-completion
curl -o "$(brew --prefix)/etc/bash_completion.d/rake" \
"https://raw.githubusercontent.com/ai/rake-completion/e46866ebf5d2e0d5b8cb3f03bae6ff98f22a2899/rake"