Create and track issues

Issues are structured records for bugs, features and other product work. For a free-form board with columns you name yourself, use Track work with Kanban boards instead. Open Issues from the navigation to see issues in the selected Personal or team context. The list shows each issue's stable identifier, title, status and last updated date.

Choose Create issue to add an issue. A title is required. Choose the team that will own it; the issue starts in Backlog with no priority. Each team has its own sequence of identifiers, beginning with MAG-1. A project can have its own prefix and overview. Issues assigned to a project use that project's prefix; unassigned issues use MAG. An issue keeps the identifier assigned when it was created. Press C outside a text field to open issue creation, or find Create issue with the command palette. The project choices change when you choose a different team.

Projects are optional groups of related issues. You can create an issue without a project and assign one later from Edit issue. Open Projects from the sidebar, then choose Create project. On Create issue, choose Create a project below the project field to make one and return to the issue with it selected; the title you typed is kept. A project belongs to one team and has a prefix unique within that team. Its overview shows the description, issue count and completed count, with its issues listed below.

Editors can change a project's name, Markdown overview, status, lead, start date and target date from Edit project. The target date cannot precede the start date. Open Roadmap to see projects with a start or target date, ordered by date with their issue completion counts. Undated projects remain on the Projects page.

Open Milestones from a project to plan named project targets. Members with edit access can create and edit a milestone's description, target date and status. A milestone can be planned, active, completed or cancelled. Removing one takes it out of the project's milestone list. Move its issues to another milestone or clear their milestone before removing it.

An issue in a project can be assigned to one of that project's milestones from Edit issue. The issue and project pages show the milestone and how many assigned issues are completed. Changing an issue's project clears its milestone. CSV and JSON exports include milestone information.

Team admins can open Statuses, then Manage cycles, to turn cycle planning on or off for the selected team. When it is on, Cycles appears in the Issues page's More menu. Editors can create a one-week, two-week or custom cycle by choosing its start date. Custom cycles also need an end date. Cycle dates cannot overlap another cycle in the team. Turning planning off keeps existing cycles and hides them from the Issues page.

Assign an issue to a cycle from Edit issue. Editors can also select issues on the Issues list and move them into a cycle in bulk. A cycle page shows the number of completed, in-progress and remaining issues, followed by issues grouped by status. The list shows up to 100 issues per page. An issue page shows its cycle when cycle planning is on. CSV and JSON exports include cycle information.

Editors can send an open issue to Triage from its issue page by choosing More, then Send to triage. The Triage page lists issues waiting for review in the selected Personal or team context. An editor can accept an issue, mark it as a duplicate of another issue in the same team, or cancel it. Accepting keeps its current status; the editor can then change its project and other properties from Edit issue. Duplicate and Cancel move the issue to a cancelled status. The review appears in the issue's activity history. An editor can send a reviewed issue back to triage.

Issues created through the version 1 API also enter the selected team's Triage queue. The API uses the same team edit permissions and workflow as issue creation in Magpie. See API keys and REST API for its routes and fields. Issues created in the Magpie app do not enter Triage; they start in the team's workflow, as they do on the website.

API users with team edit access can move an issue to Trash and restore it within 30 days. Trash is team-scoped, and its list is separate from the ordinary issue list. After the recovery period, a scheduled worker permanently removes the issue and its related history. Its underlying Chat file remains private to its owner.

Team admins can configure issue webhooks for the selected team from Webhooks. Choose an HTTPS endpoint and the events it should receive: issue.created, issue.updated, issue.completed, issue.deleted, comment.created, project.created and project.completed. A team can have up to 20 endpoints. The host must resolve to public addresses. A new endpoint's signing secret is shown once; rotate it from the webhook list if it needs to be replaced. Redirects are not followed.

Each POST includes X-Magpie-Event, X-Magpie-Id, X-Magpie-Timestamp and X-Magpie-Signature. Verify the v1 HMAC-SHA256 signature over timestamp.raw_body with the endpoint's secret before processing the payload. The signature header contains t=<unix timestamp>,v1=<hex digest>; reject a timestamp outside your allowed freshness window. The event ID stays the same when a delivery is retried, so store it to avoid applying a delivery twice. Delivery attempts use increasing delays and stop after five total attempts. Pausing or removing an endpoint, or changing its URL or event selection, cancels its pending deliveries. Successful payloads are retained for 30 days; undelivered payloads are cleared after 90 days.

Editors can create a public issue form from Public forms. Set its public title, instructions and optional project, then enable it and share its URL. Reports create issues in the selected Personal or team backlog and add them to Triage. The optional contact email is visible to people with edit access on the Triage page. A disabled form stops accepting reports; its existing issues remain in the selected context.

Editors can add optional fields for issues in the selected Personal or team context from Custom fields. Supported types are text, number, select, multi-select, date, checkbox and user. Select fields use one option per line; user fields select a current team member. Fields appear on Edit issue and the issue page. After a field has a saved value, its type and options cannot be changed. Removing a field hides it and its saved values from issue pages and exports. CSV and JSON exports include active custom field definitions and values.

Editors can create team-scoped rules from Automations. A rule can run when an issue is created, submitted through a public form, assigned, moved to another status, or given a label. It can optionally match a status, priority, label or project, then set the issue's status or priority. Rule changes appear in the issue's activity history. A status or priority change made by a rule does not start another automation run.

Editors can link a GitHub repository to a project from Edit project. On an issue in that project, add links to pull requests and commits in the connected repository. The issue also shows a branch name based on its identifier and title, which can be copied for use in GitHub. More, then Copy branch name, copies it on any issue, including one whose project has no repository. The Development section appears once a repository or link exists. Magpie stores these links but does not sync pull request status or create branches in GitHub.

When a project page is open, new issues, status changes and completion counts appear automatically. An open issue page refreshes its description, properties, comments and activity after another member makes a change. Updates resume when a hidden browser tab becomes visible again.

Open an issue to view its status, priority, assignee and due date. Members with edit access change them on the issue page itself: choose a new status, priority or assignee from the value, or click the due date to pick another. Each change saves straight away. Labels, milestone, cycle and custom fields are changed on Edit issue, opened from More, then Edit labels, milestone and other fields. The default statuses are Backlog, Todo, In Progress, In Review, Done and Cancelled. An issue can be unassigned and can have no due date. Marking an issue Done or Cancelled records the corresponding date; moving it back to another status clears that date.

To change the title or description, click it on the issue page. Press Enter to save a title. In the description, Enter starts a new line; press Ctrl+Enter (Cmd+Enter on a Mac) or click elsewhere to save, or press Escape to cancel. Links in the description still open when clicked. Descriptions use Markdown, including headings, lists, code blocks and links, and the rendered description appears on the issue page. Edit issue can also change both.

Team members can add comments to an issue in the Activity section, using the comment box at the end. Comments use Markdown and appear in time order, together with the issue's changes. A comment can be edited or removed by its author or a team admin. Removing a comment takes it out of the issue discussion.

The Activity section lists comments and changes in one list, oldest first: creation, edits, status and other property changes, label changes and removed comments. Each change is one line naming the person and the time.

Create a label from Edit issue. Labels belong to the selected team and can be assigned to more than one issue. The issue edit page lets you select up to 30 labels. A label has a name and an optional description.

Team admins can manage the workflow from Statuses. They can add a status, change its name or category, and move it up or down. A status can be removed after every issue using it has moved to another status. Backlog remains the default status for new issues. The category, rather than the status name, determines whether an issue counts as completed.

The Issues list shows each issue's identifier, title, labels, status, priority, assignee, project and last update in columns. The tabs above it show all issues, issues assigned to you, issues you created, active work, Backlog, or issues completed in the last 30 days. Search titles, descriptions and issue identifiers, or narrow the list with the status, priority, assignee, project and label filters beside the search box. A filter applies as soon as you choose it, and Clear filters removes them. Results stay within the selected Personal or team context and are shown 100 at a time. Search also matches label names and comment text on issues in that context.

Choose Board at the top of the page to see the issues grouped by status, and List to return. Each page shows up to 100 recently updated issues. Drag a card to another column, or choose Move to on the card and pick a status. Both methods update the issue's status and record the change in its activity history. Only members who can edit issues can move cards.

An issue page shows the title, then its properties (status, priority, assignee, due date, labels and any milestone, cycle, triage state and custom fields), then the description. Related issues, attachments and development links follow when the issue has any, then Activity. Labels, milestone, cycle and custom fields are changed from More, then Edit labels, milestone and other fields.

On an issue page, Related issues shows its parent, sub-issues and links to other issues. Choose Link an issue below the description and enter an issue ID to add a related, blocking or duplicate link, or to set a parent. Clear the parent field to remove the parent. Sub-issue progress counts children in a completed status. Relationships stay within the selected Personal or team context, and an issue cannot be its own parent or form a parent cycle.

Issue creators, assignees and commenters are subscribed automatically. Use Subscribe or Unsubscribe on an issue page to change whether you receive updates about it. Unsubscribing is remembered even if you comment again later. Notifications shows recent in-app updates for issues in the selected Personal or team context. You can mark each update as read.

Write @username in a comment or description to notify that team member. Mentions create a direct in-app notification and add the mentioned member as a subscriber unless they previously unsubscribed. Email notifications are off by default. Open Email settings from Notifications to opt into email for mentions, assignments, comments, or other updates to project issues. Email delivery requires the server's issue notification worker to be scheduled.

Editors can choose Attach a file below the description to attach a file to the issue or to one of its comments. The attachment form accepts a selected file, a dropped file, or a pasted image. Files can be up to 25 MB. Images show a preview on the issue page. Attachments are private to people who can view the issue, and editors can remove an attachment from the issue page.

Open More on the Issues list, then Export CSV, to download issue fields for the selected Personal or team context. Export JSON also includes projects, workflow statuses, labels, comments, activity, relationships and attachment metadata. The JSON export lists attachments but does not include the file contents.

Choose More, then Import issues, to bring in up to 200 issues at a time from CSV or a GitHub CLI JSON export. For CSV, upload a file with a header row, review its first rows, and map columns to issue fields. Title is required. Status, project, assignee and label values must match existing values in the selected Personal or team context. Due dates use YYYY-MM-DD. The optional Original ID column is kept as import metadata; imported issues receive new Magpie identifiers. The import validates every row before creating issues.

For GitHub Issues, use GitHub CLI to create a JSON file, then upload it in the same import screen:

gh issue list --repo OWNER/REPO --state all --limit 200 --json number,title,body,state,labels,assignees,createdAt,closedAt > issues.json

The import keeps the GitHub issue number as its Original ID, maps open issues to the first Backlog, Unstarted or Started status and closed issues to the first Completed status in the selected team. It imports the title, body, labels, the first assignee, and available created and closed timestamps. The assignee's GitHub login must match a member's username in Magpie. Comments, attachments and pull requests are not imported. GitHub CLI handles repository access on your computer; Magpie receives only the uploaded JSON file.

Open Display to sort the list by update time, creation time, due date or priority, or to group rows by status, project or assignee. Choose More, then Save current filters as a view, to name a combination of filters, sorting, grouping and list or board display. A saved view can be private or shared with the selected team. Open Saved views to use, edit or remove your views; shared views created by another member can be opened but not changed.

Editors can select issues with the checkbox at the start of each row, or with the checkbox in the column heading to select every issue on the page. Once an issue is selected, a bar above the list shows how many are selected. Choose Status, Priority, Assignee, Project, Cycle or Labels in that bar, then the new value, to change up to 100 issues at once. Clear selection unchecks them. The change applies within the selected Personal or team context and appears in each changed issue's activity history.

In the Magpie app

Issues in the app lists the selected Personal or team context's issues, newest change first. Search from the header, and narrow the list to Assigned to me or to one status. Choose New to create an issue with a title, an optional Markdown description and a project.

On an issue, tap the title to rename it, or tap Status, Priority, Assignee or Due date to change it. Each change saves as soon as you make it. Choose Edit description to change the description, then Save description. Read the issue's comments and add one at the end.

Editors can choose Move to Trash from the issue's action menu. Trash, in the Issues list's action menu, lists issues moved there in the last 30 days; tap one to restore it. Labels, custom fields, relations, attachments, projects, cycles, the board and the other Issues pages are on the website.

For help with issues, Contact support.