pivotal-flow 🔀

A command-line tool that helps you manage & automate your workflow to use with PivotalTracker.

Install

# install pivotal-flow globally 
# you can check if it was installed correctly by running `pivotal-flow --version` 
npm install -g pivotal-flow
 
# initialize pivotal-flow 
pivotal-flow init

pivotal-flow is built to work with husky 🐶 along with the Pivotal GitHub integration.

Commands

Run pivotal-flow --help to see usage & documentation.

you can also use the pf alias for pivotal-flow.

init

A guided questionnaire to set-up pivotal-flow with the basic configuration:

$ pivotal-flow init
# generate a basic configuration file in your home directory. 

start

Create a new story or work on an existing story (from the stories in your PivotalTracker project(s)):

$ pivotal-flow start
# start working on a story guided by a questionnaire 

git-hooks via husky

pivotal-flow also provides a few git-hooks to automate a few tasks when working with PivotalTracker as your project management tool. You can add the provided hooks using husky.

In order to use the hooks from pivotal-flow, add it as a dependency to your npm project:

$ npm install --save-dev pivotal-flow
# install it as a dev-dependency 

Then add the hooks and/or commands to your package.json:

   },
   "scripts": {
     // ...
+     "start:story": "pivotal-flow start"
   },
   "husky": {
     "hooks": {
+      "post-checkout": "pivotal-flow hook check-story-id-in-branch",
+      "prepare-commit-msg": "pivotal-flow hook add-story-id-to-commit",
+      "commit-msg": "pivotal-flow hook check-story-id-in-commit",
     }
   }
 }

Hooks

check-story-id-in-branch

post-checkout - check that all newly created branches have a PivotalTracker story id in the branch name.

Why do we need the ID in the branch?

This allows the GitHub integration to send updates to pivotal to show branch & PR information in a story.

add-story-id-to-commit

add-story-id-to-commit added as a prepare-commit-msg hook will pick up story id from the branch name (if it is present) and append it to each commit message.

Again, this allows the GitHub integration to send updates to PivotalTracker of commit information in a story.

check-story-id-in-commit

check-story-id-in-commit as a commit-msg hook - checks if each new commit message contains the story id as well.

In case you're not using the add-story-id-to-commit hook or don't want to enforce story id being present in every branch name, this hook makes sure the story id is present in the commit message (added by other means by the user).

Configuration

Once the init command is run, it creates a config file in your home directory. This is meant to be a per-user configuration.

You can modify/add the configuration file in multiple levels which are supported via cosmiconfig.

Currently, a configuration file looks like the following:

{
  "projects": [
    {
      "name": "Alpha",
      "id": 1234567
    },
    {
      "name": "Bravo",
      "id": 7654321
    }
  ],
  "pivotalApiToken": "abcde*****************************"
}

NOTE: Since the pivotalApiToken is meant to be private, we discourage adding the pivotal-flow configuration file to source control.

Configuration Options

Option	Type	Description
pivotalApiToken	string	API Token from PivotalTracker.
projects	project[]	An array of PivotalTracker projects which will be part of your workflow for creating / working on stories.
projects[i].name	string	The name of the project (or an alias) to be used when picking among projects in the different commands.
projects[i].id	string|number	Each PivotalTracker project has an id which you can find by referring to your project's URL. For example, if your project's URL is https://www.pivotaltracker.com/n/projects/1234567 then the project id would be 1234567. This is required to query the stories from the project

Commands in action

Starting a new story

Run pivotal-flow (alias: pf) as a local/global command to start creating stories from the command line:

Work on an existing story

Fuzzy search

Other

Using pivotal-flow hooks alongside Pivotal GitHub Integration ensures your updates (commits, pushes, merges etc) on GitHub are posted directly and automatically to your Pivotal stories.

Follow instructions for and the Pivotal GitHub Integration to set-up the entire flow for your repository.

Credits

The concept of adding story ids (picked from the branch-name) to all commits are from the awesome git-tracker project by @stevenharman - ported to husky/node implementation in pivotal-flow's add-story-id-to-commit hook.

References

1. PivotalTracker
2. Git Hooks
3. Husky 🐶
4. git-tracker