# Manage issue boards

## Issue boards at a glance

An issue board is a visual work area where issues appear as cards in columns. You use
it to arrange board columns, place existing issues, and manage the board record from the
Issues area.

| If you need to… | Go to… |
| --- | --- |
| See the Issues destination and its Boards view | [Issues overview](doc:issues-overview) |
| Open an existing board | [Find and open a board](#find-and-open-a-board) |
| Start a board from a standard layout | [Create or duplicate a board](#create-or-duplicate-a-board) |
| Change the board name, description, color, or columns | [Configure the board and its columns](#configure-the-board-and-its-columns) |
| Add, filter, or move issues | [Add, filter, and move issues on a board](#add-filter-and-move-issues-on-a-board) |
| Work on one issue after finding it on a board | [Work with an issue](doc:work-with-an-issue) |
| Review issue status and recovery guidance | [Issue states and recovery](doc:issue-states-and-recovery) |
| Move between application destinations | [Navigation basics](doc:navigation-basics) |

When you create a board, choose one of three templates: **Default**, **Simple**, or
**Empty**. The board record then gives you access to its columns and issue cards.

## Before you start

You need a selected project before the Boards view can load its boards. Sign in to the
application.
If no project is selected, the page shows `No project selected` and
`Pick a project from the switcher to see its boards.`

## Find and open a board

A board card is the list entry for one saved board. Open it when you want to work with
that board's columns and issue cards.

**Prerequisites**

- Select the project whose issue boards you want to use.
- Sign in to the application.

**Steps**

1. In the Issues area, open the Boards view.
2. Optional: Select **Refresh** to request the current board list again.
3. Choose the next action.

   | If you want to… | Select… |
   | --- | --- |
   | start when the list shows `No boards yet` | **Create board**; the create-board dialog opens |
   | create a board from a populated list | **New board**; the create-board dialog opens |
   | open a board that is already listed | the board card; the board record opens |

4. If the board record is open, optionally select **All Boards** to return to the board
   list.

**Result:** The create-board dialog is open after you select **Create board** or
**New board**, or the selected board record is open after you select its board card.

## Create or duplicate a board

Creating a board starts a new board record. Duplicating copies an existing board's
columns and cards into a new board, so use duplication when you want to preserve an
existing board arrangement.

### Create a board

**Prerequisites**

| Starting state | Entry action |
| --- | --- |
| The create dialog is already open after selecting **Create board** or **New board** | Begin with step 1. |
| The Boards view is open | Select **New board**, then begin with step 1. |

**Steps**

1. In **Name**, enter the board name.
2. In **Description**, enter an optional description.
3. In **Color**, select a color preset.
4. In **Start with template**, select one of the following options.

   | If you want to… | Select… |
   | --- | --- |
   | Use the four-column starting layout | **Default** |
   | Use the three-column starting layout | **Simple** |
   | Add your own columns from the beginning | **Empty** |

5. If you selected **Default** or **Simple**, select **Add all current open issues to this
   board** when the board should begin with the project's current open issues.
6. Select **Create board**.

The dialog uses `Name` as a required field and limits it to 80 characters. **Description**
is optional and limited to 500 characters. **Add all current open issues to this board**
is available for **Default** and **Simple**, not **Empty**.

After a successful creation, the application displays `Board created` and opens the new
board record.

**Result:** The new board record opens with the selected template and optional open issues.

### Duplicate a board

**Prerequisites**

- Open the board list.
- Know which saved board you want to copy.

**Steps**

1. On the board card, open **Board options**.
2. Select **Duplicate**.
3. In **Name**, review the pre-filled copy name and edit it if needed.
4. In **Description**, enter an optional description.
5. In **Color**, select a color preset.
6. Choose the next action.

   | If you want to… | Select… |
   | --- | --- |
   | create the duplicate | **Duplicate board** |
   | close the dialog without duplicating | **Cancel** |

Duplicate mode does not show **Start with template** or
**Add all current open issues to this board**. A successful duplication displays
`Board duplicated` and opens the new board record.

If creation fails, the dialog can display `Could not create the board. Try again.`

**Result:** A new board copy opens, or the dialog closes without changing the board list.

## Configure the board and its columns

Board settings control the board record itself. Columns control how issues are grouped
and which issue status a column represents.

### Update board details

**Prerequisites**

- Open the board record or the board card's options menu.
- Have a new board name ready when you change the name; the field is required for saving.

**Steps**

1. On the board card, select **Board options**.
2. Select **Edit board**.
3. In **General**, edit **Name**, **Description**, or **Color**.
4. Choose the next action.

   | If you want to… | Select… |
   | --- | --- |
   | save the board details | **Save changes** |
   | manage the board columns | **Columns** |

The **Name** field is required and accepts up to 80 characters. **Description** is
optional and accepts up to 500 characters. A successful save displays `Board updated`.

**Result:** The board settings close after the details are updated, or the **Columns**
tab opens for column management.

### Add or edit a column

**Prerequisites**

- Open **Board settings** on a board record.
- Select **Columns**.

**Steps**

1. Choose how to open the editor.

   | If you want to… | Open the editor with… |
   | --- | --- |
   | create a new column | **Add column** |
   | edit an existing column | the existing column, which opens **Edit column** |

2. In **Name**, enter the column name.
3. In **Maps to status**, select one of **Open**, **In Progress**, **Resolved**,
   **Closed**, or **None**.
4. In **Color**, select a color preset.
5. In **WIP limit**, enter a limit, or leave it blank for no limit.
6. Choose the final action.

   | If you are… | Select… |
   | --- | --- |
   | creating a column | **Add column** |
   | editing a column | **Save** |

The column name is required and limited to 60 characters. A WIP limit is optional; an
entered value has a minimum of 1. **None** is a purely organizational column mapping
that does not change issue status. A successful action displays `Column added` or
`Column updated`.

**Result:** The column list shows the new or updated column.

### Reorder or remove columns

**Prerequisites**

- Open **Board settings** and select **Columns**.

**Steps**

1. Drag a column to its new position.
2. Select a column to open its editor.
3. Select **Delete column**.
4. When other columns exist, choose the destination column for its cards.
5. Select **Delete**.
6. Select **Done** when you finish column management.

When the column has other columns available, the confirmation asks where its cards go.
When it is the last column, the confirmation says `This is the last column on the board —
delete the board instead if you want to remove everything.` and **Delete** is disabled.
A successful removal displays `Column deleted`. If saving or deleting fails, the editor
can display `Could not save the column.` or `Could not delete the column.`

**Result:** The board shows the saved column order, or the column is removed and its cards
are handled according to the selected destination.

## Add, filter, and move issues on a board

Issues appear as cards on the board. Use **Add Issues** to place existing issues on the
board, **Filter** to narrow the cards shown, and drag cards between columns to change
their board position.

### Add existing issues

**Prerequisites**

- Open a board record with at least one destination column.
- Know which existing issues you want to place on the board.

**Steps**

1. Select **Add Issues**.
2. In **Search issues...**, enter search text when you want to narrow the list.
3. In the status filter, select **Any status**, **Open**, **In Progress**, **Resolved**,
   or **Closed**.
4. In the priority filter, select **Any priority**, **Critical**, **High**, **Medium**,
   or **Low**.
5. Select the checkbox beside each issue to add, or select **Select all visible**.
6. In **Add to column**, select the destination column.
7. Select **Add issue** or **Add issues**, according to the number of selected issues.

The **Add to column** choices come from the board's saved column names. The first column
in board order is selected when the dialog opens. If no issues match, the dialog displays
`No issues to add`.

After a successful addition, the application displays `Added <count> issue(s) to the board`.
If the addition fails, it can display `Couldn't add issues`.

**Result:** The selected issues appear in the chosen board column.

### Filter the board cards

**Prerequisites**

- Open a board record with cards available to filter.

**Steps**

1. Select **Filter**.
2. In **Filter cards**, choose values under **Priority**.
3. When the board contains matching values, choose values under **Category**,
   **Assignee**, or **Audience**.
4. Under **Reporter email**, select **Any**, **Has email**, or **No email**.
5. Select **Reset** to remove the choices in the filter panel, or select **Clear all**
   from the active-filter strip.

The **Category**, **Assignee**, and **Audience** sections appear when the board has
matching values. **Priority** and **Reporter email** are always available in the filter
panel. Active choices appear in the filter strip and can be removed individually.

**Result:** The board shows only the cards that match the selected filters.

### Move a card between columns

**Prerequisites**

- Open a board record with an issue card and at least one destination column.

**Steps**

1. Drag the issue card to its destination column.
2. When the destination is at its WIP limit, review the confirmation prompt
   `<column name> is at its WIP limit (<count>). Add anyway?`.
3. Confirm the move when you want to add the card despite the limit.

If the move fails, the application can display `Couldn't move the card — please try again.`

**Result:** The card appears in its destination column, or it remains in its original
column when the WIP-limit confirmation is declined.

## When a board action goes wrong

Use this table to match the exact message to the action you were taking.

| What you see | What it means | What to do |
| --- | --- | --- |
| `No project selected` | The board screen has no selected project. | Pick a project from the project switcher, then reopen Boards. |
| `No boards yet` | The selected project has no boards in the list. | Select **Create board**. |
| `Nothing matches` | No board has an issue in the selected status filter. | Select **Clear filter**. |
| `No issues to add` | No issue matches the current add-issue search and filters. | Change **Search issues...**, the status filter, or the priority filter. |
| `Delete board?` | The board-delete confirmation is open. | Select **Cancel** to keep the board, or select **Delete board** to remove the board view. |
| `The issues themselves stay on your project — only the board view is deleted.` | Deleting a board removes its board view, not its issues. | Delete the board only when you want to remove that view. |
| `You can undo this for the next 30 days.` | The deleted board can be restored during that period. | Select **Undo** in the deletion notification when you want to restore it. |
| `Could not create the board. Try again.` | Board creation did not complete. | Review the board details and select **Create board** again. |
| `Could not save` | Board settings could not be saved. | Review the board details and select **Save changes** again. |
| `Could not save the column.` | Column creation or editing could not be saved. | Review the column details and select **Save** or **Add column** again. |
| `Could not delete the column.` | Column deletion did not complete. | Review the destination-column choice and select **Delete** again. |
| `Couldn't add issues` | The selected issues were not added. | Review the destination in **Add to column** and try again. |
| `Couldn't move the card — please try again.` | The card move did not complete. | Return the card to its intended column and try the move again. |
| `Couldn't restore — try the boards index` | The restore action did not complete. | Open the Boards list and try the restore action there. |

## Continue with the board's issues

After you finish board maintenance, continue with the individual issue represented by a
card or review the issue's status guidance. Creating a board opens its new board record,
and deleting a board leaves the issues on the project even though the board view is gone.

| Continue with… | Read… |
| --- | --- |
| An individual issue record | [Work with an issue](doc:work-with-an-issue) |
| Issue statuses and recovery | [Issue states and recovery](doc:issue-states-and-recovery) |
| The Issues destination and board entry point | [Issues overview](doc:issues-overview) |