Pivotal Tracker Help

Getting Started

What is Pivotal Tracker?

Tracker is a simple, story-based project planning tool that allows teams to collaborate and react instantly to real-world changes. It's based on agile software development methods, but it can be used on a variety of types of projects. Tracker frees you up to focus on getting things done, without getting bogged down, keeping your plans in sync with reality.

Pivotal Tracker embodies—and encourages—a practical agile software development process, as pioneered by Pivotal Labs.

The Dashboard

When you first sign in to Tracker, you'll find yourself on the Dashboard. This page gives you an overview of your most recently used projects and workspaces, as well as easy access to create new ones or adjust their settings.

Dashboard, no projects Dashboard, populated

You'll see any project you’re involved with in the list. Clicking on any of the icons (e.g., Settings, Members, or Reports) will take you to relevant page for each of those. Mousing over Volatility and Velocity (more on those below), or the bars on the activity chart below them, will give information about them. Clicking the project name will take you to that project's stories.

Project detail

Instead of beginning at the Dashboard, you can also choose to start at the project you most recently visited, under your Profile (under your username at the top right of the Tracker page).

The Project Page

You'll spend most of your time in Tracker on the project page, working with stories. You can switch between projects by using the Projects and Workspaces dropdown at the top left of the page (More on Workspaces below). Within a project, you'll work with stories in several different panels. When you first open a project, you will see two panels open: the combined Current/Backlog panel and the Icebox.

Project Dropdown Next
Split Current/Backlog

The top of the panel shows the iteration currently in progress. If there are more stories in the panel than can be completed in the current iteration, you’ll see an iteration bar that is the start of the Backlog. The Backlog shows iterations that will occur in the future. Each iteration holds stories whose point total adds up to the team's velocity. Therefore, the top set of stories between the first and second iteration bar contains stories that will be completed in the current iteration. You can always split this panel into a Current and a separate Backlog panel by clicking the link icon at the bottom.

Iteration bars have options that allow you to expand and collapse an iteration, override its iteration length, and set team strength. Mouse over the iteration date for a tool tip with the full date range.

You can open other panels by clicking on their names in the sidebar at the left or with keyboard shortcuts (type “?”, or select Keyboard Shortcuts under the Help & Updates menu to see them).

Iteration Header
  • My Work shows the stories you own (i.e., the ones you're working on) and the stories you requested that are ready to be accepted.
  • Icebox features stories that have yet to be prioritized. Stories can stay in the Icebox indefinitely, while they are “on ice.” When ready, you can prioritize a story in the Icebox by dragging it into the Current or Backlog panel.
  • Done displays the iterations that occurred in the past. Done iterations contain stories that have been accepted, in the order in which they were accepted.
  • Epics highlight big-picture themes or large features that consist of multiple stories.
  • Labels provides a clickable list of labels in the project (mouse over them for options). All labels are clickable wherever you see them.
  • Saved Searches shows you a clickable list of the searches you have saved, which you can access by clicking the heart icon at the bottom of the Search panel. Click the heart again to remove the saved search.
Save Search Heart
  • Charts gives you a release burn-down chart, velocity by iteration, current iteration burn-up, and a breakdown of story types.
  • Project History identifies updates that have been made to stories.

You can control fixed panel width by using the controls and slider at the bottom of the sidebar. Click Fixed to select Auto mode and have the panels automatically fit the open panels to the browser.

Other sidebar options include:

  • Sidebar Collapse button

    Automatically collapse and expand the sidebar by clicking the icon at its top left.

  • Story Density menu

    Adjust your story density (i.e., change the amount and type of information in collapsed stories).

  • Project Color menu

    Choose a color for your project, which shows on the Dashboard and helps differentiate its panels in a Workspace.

  • Project Settings menu

    Access your Project Settings.

Note: Only a project owner, an account admin, or the account owner can edit Settings, add and remove members, or configure integrations.

You can drag and drop panels into a different order using the panel header, and your panels are remembered, per project. This is your personal view of Tracker; it cannot be shared, and your layout does not affect anyone else’s.

The panel footer has options specific to that panel, too. Mouse over each icon to see a tooltip for what it does:

Footer icons

Creating Stories

Expanded Story
Add Story

A story represents one concrete deliverable or task. To create a new story in Tracker, click the Add Story button at the top of the project page, or just hit the 'a' key. This will open a story detail window in the icebox. The only information that is needed to save a new story is its title - everything else is optional, and can be captured later. The story title is a brief, one-sentence description of a concrete, independent requirement, such as "A user can request a password reset". To elaborate on the story, you can enter more information into the description field.

The user who created the story becomes the "requester", but that can be set to any project member. Ideally, this is someone who speaks for (or is) the project's customer, and can make decisions about story requirements and acceptance criteria.

The owner is the person who will be responsible for implementing the story (normally a developer). It's not necessary to identify an owner when the story is initially created - Tracker allows anyone to start a story. On a typical project, team members start stories from the current iteration (or the top of the backlog) when they finish work on the last story.

You can choose a point estimate, by clicking on one of the buttons in the points field. A point estimate is a relative measure of complexity and risk. New stories start out as un-estimated, and can be left that way until later. In fact, stories are often estimated a few iterations before they are started; that is when more is known about what they will entail.

The labels field allows you to add arbitrary tags to the story, which can represent larger feature themes, or indicate something special about the story, for example that it "needs design". Type into the Labels field to create a new label or choose an existing one, or click on the down-arrow button in the field to see and select from existing labels.

You can come back to a story and change any of its details later.

Types of Stories

There are four types of stories in Tracker: Features, Chores, Bugs, and Releases.

Feature Features are stories that provide verifiable business value to the team's customer (e.g., "Add a Special Instructions field to the checkout page," "Purchase history should load in half a second," and "Add a new method addToInventory to the public API"). Features are worth points and therefore must be estimated.

Chore Chores are stories that are necessary but provide no direct, obvious value to the customer (e.g., "Update SSL Certs"). They shouldn't need extra validation, so the states for chores are just Unstarted, Started and Accepted.

Bug Bugs represent unintended behavior that can be related to features (e.g., "Login box is wrong color" or "Price should be non-negative").

Release Releases are milestone markers that allow your team to track progress towards concrete goals (e.g., stakeholder or investor demos, software launches, etc.). It's possible to specify target dates for releases (more on those below). All stories for a milestone or release should go above the marker for it.

To help with the big picture, Epics can be used to describe, discuss, and visualize the progress of large features or themes that are larger than individual stories (more on epics below).


Stories are estimated in points, which are a relative, team-specific metric representing the effort it will take to complete a given story. When starting out with Tracker, it helps to ground a point in something concrete (e.g., how much can be done in an ideal day, or a typical small feature). Over time, points become more intuitive (more on points below).

When estimating a story, you choose a value from one of Tracker’s point scales. You can choose from three default scales: Powers of 2, Linear, and Fibonacci, or create your own scale by choosing Custom from your Project Settings. This is to encourage consistency in the granularity of stories. In general, most stories should be small (i.e., 1–2 points). Stories with larger estimates may hide unknown complexity, and should ideally be broken down further.


The easiest way to estimate stories is to click an Estimate button on a story. Only unestimated stories have these buttons; once a story is estimated, you'll see a Start button instead. To change the estimate of a story, expand it (to show its details) and change the value in the Estimate dropdown.

Commenting on Stories

Tracker facilitates discussions about a story through comments. Comments are a trail of the thinking around a story, and can only be edited or deleted by their original author or a project owner. They can include attachments, such as design mock-ups, screenshots or anything else that will help a story be worked on. Any team member can comment, and all story commenters can choose to receive email notifications and/or in-app notifications.

Following Stories

To make sure you receive notifications on specific stories, use the “Follow this story” checkbox in the expanded view of a story or epic. You will receive notifications for all comments posted to stories or epics that you follow, unless you've disabled them on your Notifications Settings page.

To have someone else follow a story, just @mention them in a comment on the story.

Story Previews and Information

You can see when a story was created (or requested) in story previews. You can also see that in an expanded story if you click the “last updated” section.

You can also see a preview of other stories or epics (including where links to them were pasted in an expanded story) by mousing over them.

When you mouse over a collapsed story, you can see a preview of what’s in it.

To see exact dates in the Project History or a Story History panel, mouse over the items to see the number of minutes, or approximate number of hours ago, an action was performed.


New stories begin their life in the Icebox, or "on ice." You can rearrange stories in the Icebox by dragging them up and down, but the order of stories within the Icebox is useful for organizational purposes only.

The Backlog holds prioritized stories. Stories at the top of the Backlog are the most important, and will be worked on first. To prioritize a story, drag it from the Icebox to Backlog, or the current iteration. There are also drop zones at the bottom of each panel. (Sometimes stories move directly into Current when you drop them in the Backlog; this is because the number of points that can fit in the current iteration is determined by the project's velocity.)

Stories that have been started stay in a group at the top of Current, but you can change priorities for unstarted stories at any time by dragging them anywhere in the Current or the Backlog panel. You can also put an unstarted story back into the Icebox.

Story Workflow

In brief, the simplest Tracker workflow goes as follows:

  1. Customer/PM/PO prioritizes stories in Backlog.
  2. Team discusses and collectively estimates each story.
  3. Developers start next available story in Current or Backlog.
  4. Developers check in code to finish story.
  5. Team pushes code for new feature to demo/test environment, and delivers stories.
  6. Customer/PM accepts or rejects story (the feedback loop).

To elaborate more on Step 3: At the beginning of a typical day, a developer will pick an unstarted story in the current iteration and click its Start button (thereby becoming its owner).

When work on the story is completed, the developer will click the Finish button. The Deliver button will appear; when the product is ready for acceptance testing/evaluation, a team member will click the Deliver button. This will indicate to the story requester (visually in Tracker and via notifications) that they can now provide feedback on the story by accepting or rejecting it.

If the story requester (or someone else representing the customer) accepts the story, the story will turn green and move to the top of the current iteration. At the end of the iteration, accepted stories move to the Done panel.

If the story is rejected, its state will be set to Rejected, and a Restart button will appear. This indicates to the owner of the story that more work is needed. When a collapsed story is rejected, Tracker prompts the rejecter for a reason, which subsequently appears as a comment in the story. If an expanded story is rejected, there’s no prompt, but a comment should be added. The owner(s) of the story receive a notification.

Things that are stalling workflow can he highlighted using labels such as “blocked,” “needs design,” or “needs discussion.” You can use labels (like “as designed”) if you want to accept a story as one that won’t be worked on and want to preserve the reason why. You can also label all stories planned for a specific release to help clarify what’s happening in your project.

Points + Velocity

A point is a relative, team-specific measure of the effort it will take to implement a feature. Tracker allows you to estimate feature stories using a fixed-point scale, configured per project.

Currently, Tracker supports three default point scales: Linear (i.e., 0/1/2/3), Powers of 2 (i.e., 0/1/2/4/8), and Fibonacci (i.e., 0/1/2/3/5/8). You can also create your own custom point scale. Only features are estimated, because only features contribute to "business value." Bugs and chores are part of normal engineering overhead, and are not normally estimated (this can be enabled for some projects if you wish, but it’s not recommended). To use your own set of point values for your project, go to your Project Settings, choose Custom in the Point Scale dropdown, and enter a list of numbers, separated by commas.

Custom Points, Expanded

When using a custom point scale, the estimate values will appear as numbers, instead of the bars that you see when using one of the default point scales. Unestimated stories will show the first five point values, which you can click to select. If your point scale has more values, you can choose one of them to estimate a story by clicking the “+” button on the right.

Velocity is a measure of project output. It's the average number of feature story points accepted in the last few iterations (i.e., 1–4). Tracker calculates velocity automatically, and uses it to predict the number of iterations a given backlog of stories will take to complete.

It's possible to override calculated velocity in your view of the project and experiment with hypothetical scenarios. Click the Velocity link to specify a speculative value and see what the impact on the Backlog or future releases would be. No other users see the change when you override velocity. You can click Revert to revert it back to its true value. Overridden velocities are not stored, so velocity reverts to the calculated value when you reopen the project.

At the beginning of a project, Tracker will use a default initial value for velocity, as specified in Project Settings. It will also revert to this default velocity after a number of iterations with 0 accepted points.


Volatility is a measure of how consistent your project’s velocity is. While velocity shows you what will be done, based on the rate at which recent work has been completed, volatility shows how reliable that is. A low volatility tells you that estimates are accurate and that you can be confident about what will be done in each iteration.

You can see information about your most recently visited projects on the Dashboard, including their current volatility. This is a percentage, computed using the number of recent iterations set in each project’s settings for Velocity Strategy by a project owner. If you mouse over the volatility, you’ll see which iterations were used to calculate volatility and velocity.

Release Deadlines

Tracker allows you to monitor progress toward a fixed date release through the use of release deadlines. To specify a deadline, expand the release story and enter a date in the Deadline field. Tracker will show this deadline as a thick line in the Backlog, at the end of the iteration in which the date falls. As the scope of a particular release (the number of points above the release marker) and project velocity change, the release will move accordingly, but the deadline marker will stay fixed to a particular iteration. If the release marker moves past the deadline, it will turn red. This is a great way to manage scope creep and experiment with different what-if scenarios.

To remove a deadline from a release, expand the release, and click the "clear" link.

Epics, for the big picture

Epics allow your team to plan, discuss, and monitor the progress of coarse-grained features or themes, at a level higher than individual stories.


Epics are similar to stories, but they live in their own panel, and can be ordered independently of stories in the Backlog to make the project's big picture priorities obvious to the whole team.

You can also use epics for design collaboration on big features, and make it easy for developers to find assets (such as mock-ups) for a big feature that spans many stories.

Epics are tied to stories via a special label called the linked label. Apply this label to stories to make them part of the epic. Labels linked to epics are purple, instead of the usual green.

Click on Epics in the sidebar to show the Epics panel, or just type Shift-E. The “+” button at the top of the Epics panel creates a new epic. You can also convert existing labels to epics in the Labels panel.

Epics allow you to see where you are with big features at a glance. As you prioritize and work on stories associated with an epic (via the linked label), a multicolor progress bar will appear on the epic, allowing you to see how big the given epic is relative to other epics, and to easily see how much of the epic has been accepted, is in progress, prioritized, or on ice. You can hover over the progress bar with the mouse to see a more detailed breakdown, as well as estimated completion date, which is the last day of the iteration that the epic's last prioritized story appears in, in the Backlog. Clicking that progress bar, or the small arrow button to the right of it, reveals all of the epic's stories.

Drag and drop stories within an epic's story list to reprioritize them relative to each other. Dragging a story from the Icebox or Backlog to an epic's Story List panel will move that story to that position and associate the story with the epic. Dragging and dropping stories on the epic itself, in the Epics panel, just associates the stories with that epic, without moving them to a new position.

Searching for Stories

Use the Search field at the top of the project page to find stories. Tracker will search titles, descriptions, tasks, uploads, and comments, and display matching stories.


The reveal button can be used to highlight the story in context (e.g., in the Backlog or the Icebox).

Working with Multiple Stories

It's possible to select a number of stories and perform a few common tasks including Move to Icebox, Move to Backlog, and Delete.

Select stories by clicking the small square selection box to the right of collapsed story titles, and use the options that appear at the top left of the project page to perform an action. Other actions include application of labels, moving stories to another project, cloning stories, and exporting them.

Multiple stories
Select All cog

You can select a range of stories with Shift+click or the Select All option in the cog menu at the bottom right of panels. Stories are not deselected after an action is performed on them, so be careful to deselect them using Deselect All or by clicking them again once you have completed the action you wanted.

Selected stories options

Working with Multiple Projects

Workspaces allow you to view Backlogs side by side, drag and drop stories between projects, search across all the projects in the Workspace, and see all My Work stories for them.

Projects and workspaces dropdown

You can create, manage, and view Workspaces from the Dashboard. Then, with a few clicks, you can add the set of projects you want to see in a Workspace.

Empty workspace

More Information

For more information and help, see the Frequently Asked Questions page, the Help & Updates menu, as well as our blog.