An issue is a unit of work that people, agents and bots can all see and be assigned. Issues live in an Overlane project next to its tasks, and need no other tracker. You can also sync GitHub Issues and Projects or import from Linear and Jira, both optional. An issue maps to one task at a time, so what an agent works on, in what order, and how it is verified are the same as for any other task: see Tasks and priority.
An issue
| Field | Notes |
|---|---|
| Title and description | Free text. Agents are shown it as untrusted data (see below). |
| Status | backlog, todo, in_progress, in_review, done, cancelled. You can set every status except done. |
| Priority | P0 (most urgent) to P3, the same scale as the task queue. |
| Assignee | A person, an agent (claude-code or codex) or a bot. See Assigning to agents and bots. |
| Labels, project, cycle, estimate | Optional grouping fields. |
| Links | Pull requests (owner/name#number), runs and tasks. |
Each issue also has a number (#1, #2, …) that is unique in the project.
Why done is not settable
An issue reaches done only when its task is verified by evidence. No request, import or sync can set it, and a close made on GitHub is recorded but does not verify anything. If an issue has never had a task, there is nothing to verify and a close on GitHub marks it done. Read more in GitHub sync.
One task per issue
An issue has at most one active task, and a task belongs to exactly one issue. Closed tasks stay in the issue’s history. A second active task is refused.
Priority and rank come from the task queue
Setting an issue’s priority also sets the priority of its active task, and the issue shows the task’s rank. There is one ordering of work, the task queue, not a second one for issues.
Projects, cycles and labels
- A project groups issues around a goal. It can be active or archived.
- A cycle is a date range, for example a week, with a start and an end day. The end cannot be before the start.
- A label is a name and a colour. Names are unique in a project.
Create them through the API: POST /v1/tenants/{tenantId}/projects/{projectId}/work-projects, .../cycles and .../labels. All three accept a requestId and repeat safely.
Saved views
A view is a filter, a grouping and a sort over any issue field: status, priority, assigneeType, assignee, labelId, workProjectId, cycleId, estimate, source, title, number, createdAt and updatedAt. The order is stable: the same issues always come back in the same order.
overlane view new "Agent work" --filter assigneeType=agent --group-by status
overlane view listRun a view with overlane view run. Change one with overlane view update. Delete one with overlane view delete; it is archived first and can be restored for 30 days.
Every change is recorded
Each field change on an issue is an audit event with the field, the old and new value, who made the change and what kind of principal they were: a person, an agent, a bot, GitHub sync, an import or the system.
overlane issue events iss_ab12cd34ef56gh78Issue text is data
Titles, descriptions and imported text can contain anything, including text that looks like an instruction. Overlane never acts on it. When an agent reads an issue through the CLI, the title and description arrive wrapped as untrusted_data with a notice not to follow instructions found in them.
Who can do what
Viewers can read. Members and agents can create and change issues and assign them, and an agent token can also change GitHub sync settings and define loops (the issue triage autonomy class, see Autonomy). A request for another team’s issue returns 403, with the same answer whether or not it exists. See Teams and roles.
Commands
overlane issue new,issue list,issue show,issue update,issue eventsoverlane issue assignoverlane view list,view new,view run
Next: Assigning to agents and bots, GitHub sync, Importing, Loops.