# Add a diagram to a Jira issue

To add a diagram to a Jira issue, open the issue, add the **Diagram** panel from the apps button under the summary, and select **Add Diagram**. Pick a diagram type such as Mermaid, draw.io or BPMN, draw or write it, give it a title and select **Save**. The diagram is saved as an attachment on the issue.

---

## Before you start

* Capable Diagrams for Jira is installed on your site.
* You can add attachments to the issue. Without that permission the panel is read-only.

---

## Steps

1. Open the issue.
2. If there is no **Diagram** panel yet, select the apps button under the issue summary and choose **Diagram**.
3. In the panel, select **Add Diagram**, or **Add** if the issue already has diagrams.
4. Choose a diagram type in the picker.
5. Draw or write your diagram.
6. Type a name in **Title**.
7. Select **Save**.

![Jira issue with a Diagram panel showing two diagram tabs, Order states and Idempotent checkout, and a Mermaid sequence diagram preview with View, Edit and Add buttons](https://help.gocapable.com/images/a7c1943e-db43-4027-9e06-3daf7fbdbf20.webp)

Once saved, each diagram appears as a tab in the Diagram panel with a preview underneath. Select Add to put another one on the issue.

---

## What happens next

* The diagram appears as a tab in the **Diagram** panel, with a preview underneath.
* It is stored as an attachment named after its title, with an extension for its type, such as .mermaid or .drawio, so it travels with the issue like any other file.
* The **Diagrams** section in the issue's details shows how many diagrams the issue has, and you can add one from there too.

## If it does not work

* No **Add** button: you cannot add attachments to this issue. Ask a project administrator.
* The app shows a licence banner instead of the panel: see [Something is missing or looks wrong](https://help.gocapable.com/jira-diagrams/something-is-missing-or-looks-wrong.html).

---

## Related

### [Diagram (issue panel)](https://help.gocapable.com/jira-diagrams/diagram-issue-panel.html)

Every control on the panel.

### [Create / edit diagram editor (shared by all surfaces)](https://help.gocapable.com/jira-diagrams/create-edit-diagram-editor-shared-by-all-surfaces.html)

The editor and its type picker.

### [Diagrams stored as ordinary Jira attachments](https://help.gocapable.com/jira-diagrams/diagrams-stored-as-ordinary-jira-attachments.html)

Where the diagram file lives.

### [Edit a diagram on a Jira issue](https://help.gocapable.com/jira-diagrams/edit-a-diagram-on-a-jira-issue.html)

Change it later.

---

_The picture belongs on the ticket, not in a chat thread._