Managing Your Workflow States

Your Workspace comes with 5 default Workflow States that fall into the 4 Workflow State types (Backlog, Unstarted, Started, and Done). You can keep these default Workflow States as is, edit them, or delete them and add your own -- it’s up to you.


The default Workflow State is "To Do", which means any story created without a State (for example, by using our API) will be assigned to that Workflow State by default.

To change which Workflow State is the default, click on the drop-down menu (which is found in the Default State description), then select your new default workflow state. 

Also, by default, if a Story is moved into a started state without an Owner, we auto-assign the current user as Owner, but you can toggle this setting for a specific Workflow by toggling the Auto-assign Owner option.

Some ideas to get you started:

  • Add a new Workflow State under the "Unstarted" category named "Needs discussion" 
  • Add a new Workflow State under the "Started" category named "Ready for QA" 

Creating a new Workflow State

To create a new workflow state, go to Settings > Workflows States and click on the "Add +" action next to the Backlog, Unstarted, Started, and Done States.


Give your new Workflow State a name, describe the Workflow State for your Team members if you like, and add a Commit Verb that can be used to move the Story forward to this State when you make GitHub commits only. Please note, Commit Verbs will only advance a Story forward through Workflow States. They cannot be used to move a Story backwards through States.

Once you’re finished, click Save Changes.


Editing a Workflow State

To edit an existing Workflow State, go to Settings > Workflow States, find the Workflow State you’d like to edit, and click on the pencil symbol on the right side of the Workflow State.

Edit the fields you want to change, then click the Save Changes button.

Edit Workflow State.gif

Adjust the Workflow State Position

Workflow States can only be shifted up or down (i.e. left or right on the Stories page Kanban view) within the default State type (i.e. Backlog, Unstarted, Started, or Done). To adjust the position, you can do that by going to Settings > Workspace Features > Workflows.

Find the icon to the left of the Workflow State name that you want to move, click and hold, then drag and drop to adjust the position.



Deleting a Workflow State

To delete an existing Workflow State, go to Settings > Workflow States, find the Workflow State you’d like to edit, and click on the pencil symbol on the right side of the Workflow State.

In the menu that opens, click on the "Delete State" action below the description field. You’ll be asked to confirm that you want to delete the Workflow State. Please note this action cannot be undone. When ready, select, "Yes, Delete". 

The Workflow State will disappear from the State list, and you’ll see a success message pop up in the lower right confirming that the Workflow State was deleted.

Delete Workflow State.gif

Having Trouble Deleting a Workflow State?

To start, navigate to Settings > Workspace Features > Workflow States and select the Workflow you wish to delete from the dropdown.

You'll see that hovering over the Story symbol under each State will let you know how many Stories/Story Templates are associated with the respective State. Selecting this icon will open a Search page with the Story or Stories, both active and archived, in that State.


From this Search page, you can bulk edit those Stories to be reassociated to a new Workflow State or deleted entirely.

  • Please note that only 25 Stories are shown at a time, but you can select "Load More" at the bottom of the results to show another 25 and up to 500 Stories can be bulk edited at a time.
To continue with the deletion of a Workflow State:
  • Ensure the number of Stories or Story Templates left in this State is at 0 to move forward with the deletion.

  • If for some reason this auto-populated Search is giving you trouble, check out this article on Working with Stories.

To check if there are Story Templates in this Workflow State that need to be deleted, navigate to Settings > Story Templates
Make sure it's not your default State -  you can't delete that.

Make sure it's not the only Workflow State.



Was this article helpful?

2 out of 3 found this helpful

Have more questions? Submit a request