# Tickets

> Bind a run to a ticket: markdown files in your repository, or your own tracker through a bridge of yours.

A run can be bound to a ticket. The ticket then moves as the run does, and the
run's record names it.

## Tickets as files in your repository

The simplest: tickets are markdown files, kept in git.

```yaml
work_item:
  provider: markdown
  markdown: { dir: droost/tickets, prefix: TICKET }   # these are the defaults
```

A ticket is a file like `droost/tickets/open/TICKET-12-events-page.md`:

```markdown
---
title: Add an events page
status: ready
ticket_number: 12
---

## Summary

A page listing upcoming events, newest first.
```

The states are `backlog`, `ready`, `in_progress`, `review` and `done`.

```bash
droost workflow:ticket list                          # anyone
droost workflow:ticket show TICKET-12                # anyone
droost workflow:ticket new --title="Fix the footer"  # anyone; files in backlog
droost workflow:ticket move TICKET-12 done           # yours: a person's move
```

Start a run on a ticket and it moves to `in_progress`; when the run completes
it moves to `review`. Only a person moves a ticket to `done`.

droost files tickets too. At `low` and `medium`, if the whole browser suite
fails only in tests the run never touched, it files a **follow-up** ticket
instead of failing the run, and the report names it.

## Droost Cockpit (coming soon)

Droost Cockpit, a central place to run several agents at once, will feed
tickets to droost and show every run's progress. It is not available yet.

## Your own tracker (Jira and others)

droost does not talk to Jira itself. A team's own layer does, using:

- a `work_item:` block that holds the tracker's settings (projects, issue
  types, field ids under names you choose), which droost validates and shows
  but never acts on;
- a **wall**, so the agent cannot write to the tracker on its own (see
  [Hooks and walls](https://droost.org/docs/hooks-and-walls.md));
- **hooks**, to update the ticket when the run moves;
- an **operator-only script** for the writes a person approves.