---
title: "Issues, projects and views"
description: "How issues, projects, cycles, labels and saved views work in Overlane, how an issue maps onto a task, and why an issue only closes on evidence."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.overlane.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Issues, projects and views

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](/issues/github-sync/) or [import from Linear and Jira](/issues/import/), 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](/task-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](/issues/assigning/). |
| 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](/issues/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](/cli/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.

```sh
overlane view new "Agent work" --filter assigneeType=agent --group-by status
overlane view list
```

Run a view with [`overlane view run`](/cli/view-run/). Change one with [`overlane view update`](/cli/view-update/). Delete one with [`overlane view delete`](/cli/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.

```sh
overlane issue events iss_ab12cd34ef56gh78
```

## Issue 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](/autonomy/)). A request for another team's issue returns `403`, with the same answer whether or not it exists. See [Teams and roles](/teams-and-roles/).

## Commands

- [`overlane issue new`](/cli/issue-new/), [`issue list`](/cli/issue-list/), [`issue show`](/cli/issue-show/), [`issue update`](/cli/issue-update/), [`issue events`](/cli/issue-events/)
- [`overlane issue assign`](/cli/issue-assign/)
- [`overlane view list`](/cli/view-list/), [`view new`](/cli/view-new/), [`view run`](/cli/view-run/)

Next: [Assigning to agents and bots](/issues/assigning/), [GitHub sync](/issues/github-sync/), [Importing](/issues/import/), [Loops](/issues/loops/).

Source: https://docs.overlane.app/issues/index.mdx