User guide

Project configuration

Every organization ships with a sensible workflow and can bend it to whatever the team actually does. This page is the admin tour of those knobs - what each one means, and what the app refuses to let you break.

for Owners and Admins organization-wide, project-overridable settings live under one page

Where configuration lives

Open your organization and go to Settings. (Only Owners and Admins see it - and an Admin of a parent organization can configure every team below it.) The page groups the knobs into Membership (the email-domain rules from Organizations and people), Project workflow, Work item workflow, and API tokens. Each row has a Configure button; everything below walks those editors.

Two catalogs: project statuses vs work-item statuses

The most common misunderstanding, so start here: Project statuses and Work item statuses are separate catalogs with separate editors. A project's status describes the container's life - Planning, Active, On hold, Completed, Archived - and moving a project to On hold or Completed is what hides its backlog from everyday views. A work item's status describes a piece of work's life, and those names are yours to define. New projects and new work items each start at their catalog's default.

Work item statuses

The statuses editor lists your workflow in order, each with its color and a Default for new work badge on the one new items begin in; Make default moves that badge. A status carries a semantic category - To do, In progress, Done or Cancelled - and the category, not the name, is what the app reasons about. The page says it plainly: Done and Cancelled statuses are terminal. Only Done statuses count toward delivery progress; Cancelled work is removed from the delivery total. So you can call a status "Shipped", "Deployed to prod" or "QA-approved" - what matters is which category you file it under.

Retire a status by unchecking active rather than deleting: old items keep their history, the status leaves every picker, and its transition rules are retained as history. The one thing the editor refuses: you cannot retire the current default - choose another default first.

Allowed transitions

Statuses are the vocabulary; transitions are the grammar. The editor is a matrix - rows are the current status, columns the new one; clear a checkbox to block that change. Nobody can make a move the matrix blocks, in the web UI or through the API, and blocked options show up disabled, not hidden, so people can see the shape of the workflow they are in. A status never needs a transition to itself.

The page watches its own grammar: a Workflow health warning appears when a status is a dead end (work can arrive but never leave) or when the default status has no allowed path to any active Done status. Below the matrix, a history lists who changed which rule and when.

Priorities and labels

Priorities are the triage vocabulary: names, colors and an order that is itself meaningful (the list runs from most to least urgent), one default for new work, and the same retire-don't-delete rule. Unlike statuses, priorities carry no semantics - automation and reports read the code, people read the name.

Labels have no editor at all, on purpose: type a new label into any work item's Labels field and it exists, organization-wide, from that moment. Labels already in use are suggested when you tag an item, so a team's vocabulary converges without a gatekeeper.

Types and the hierarchy

The Work item hierarchy page decides which kinds exist here and how they may nest - "which trees you allow, not just which nodes". Start from a preset (Recommended product delivery, whose primary path is Epic → Feature → Story → Task → Subtask while still letting supporting work sit directly under a feature; or Flexible hierarchy, deliberately permissive - nearly any type at the root and under nearly any other, with Subtask staying terminal and Epic staying top-level), then fine-tune; touching any checkbox switches you to Custom. Four sections:

  • 1. Allowed work item types - uncheck a type to disable it. Built-in codes cannot be deleted, and no type can be disabled while existing items still use it.
  • 2. Allowed root-level work item types - what may sit at the top of a project. A task-only team allows just Task here (the page spells out that playbook).
  • 3. Container types - which kinds are grouping shells rather than executable work. Agents claiming next leaf work skip containers and pick up only the executable leaves.
  • 4. Allowed child work item types - the nesting rules per type.

Below the built-ins, Custom work item types adds organization-specific kinds: give a code and a name, and saving creates the type, enables it, and allows it at the project root so you can tune its relationships next. Type codes are permanent - they appear in history, exports and the API - and a type cannot be removed while any item still uses it.

Automations

The Automations page states its own model: "When something happens to work in <organization>, do these things - in this order." A rule has three parts:

  • When - one trigger: a work item is created, its status changes, or its assignee changes.
  • Only for work like - optional matchers on type, priority, labels and iteration (plus "from" and "to" status on the status trigger). Empty means "any".
  • Then do these, in order - up to five actions: set status, set assignee, add label, add comment, set a due date in N days, or move to an iteration.

Rules run top to bottom across the organization, and each one is org-wide unless it names a project - so a platform team sets the defaults and a product team overrides them where it works. Reorder with the arrow buttons, pause with Turn off, and know that deleting a rule keeps the history it already wrote.

The guardrails are the reason this is safe to enable: a rule that sets a status can set off other rules, and that cascade is bounded to three rounds - if it still has not settled, it stops and says so instead of hanging your click. A rule pointing at a retired status or a departed member skips that action and reports it; the person who moved the card is never punished with a failed save. And every change an automation makes is recorded with the rule's name, not the human who happened to trigger it, so the audit trail reads honestly.

Project-level settings

A project inherits all of the above and adds its own few choices, on its edit page: the key that prefixes its item references (ENG-1), its status from the project catalog, a progress mode - no progress tracking, time-boxed schedule, completed work items or completed story points - which decides what the progress bar on the project page actually measures, plus watchers, the linked GitHub repository and delivery-evidence display.

Keep going