Importing
Bring issues in from Jira, Linear, YouTrack, Monday.com, or any CSV with a header row.
Administration → Import. Workspace owners and admins only: it writes issues in bulk and reads a file containing somebody's whole tracker.
Why it is column-mapped rather than four parsers
Two of the four sources have no fixed format.
A Monday export is the board's own columns, named by whoever built the board. A YouTrack CSV is whatever the person exporting chose, and status, priority and type live in custom fields rather than in columns with reserved names. A parser written against "the Monday format" would be correct for exactly one customer.
Jira and Linear do have stable columns, and Félagi knows them —
Issue key, Summary, Issue Type for Jira; Id, Title, Status for Linear.
Those come from the exporters themselves rather than from guesswork.
So: columns are detected by name, the detection is shown to you, and anything wrong is a dropdown rather than a support conversation.
The dry run is the feature
Nothing is written until you press the second button.
What this would do
412 created 0 updated 3 skipped 415 rows read
Along with:
Which column we think means what. Correct any of them and the counts recompute.
Every status, priority and type in the file, and what each becomes. Only the values actually present — a mapping screen listing sixty statuses nobody uses is a screen nobody reads. Anything we could not map is highlighted, because an import that silently turns Blocked into Backlog has destroyed the one thing somebody needed to know.
Assignees with no account here, by name. Those issues arrive unassigned.
The first few rows as we read them, with the status mapping applied, so a wrong guess is visible rather than inferred.
What it does with what it finds
| Status, priority, type | Mapped, with sensible defaults per source. Unmapped becomes Backlog and is reported |
| Parent / Epic Link | Linked after everything exists, so a row referring to an epic further down the file still works |
| Created date | Kept. A backlog that all appeared this morning is a backlog with its history erased |
| Description | Escaped and wrapped in paragraphs — their markup is Jira wiki or Linear markdown, and neither is our HTML |
| Estimate | Read the way Félagi reads estimates (2h 30m, 1d, a bare number as hours). Story points are not hours; a team using points gets a number consistent with itself |
| Assignee | Matched on email first, then name |
Nothing is invented
An assignee with no account here leaves the issue unassigned and appears in the report. Félagi will not create accounts from a spreadsheet — that would be a migration that silently grants people access.
Running it twice is safe
Issues are keyed on (workspace, source, issue key), and that is a unique index
rather than a hopeful lookup. The most common way a migration goes wrong is
somebody running it a second time because they were not sure the first one worked.
A second import updates rather than duplicating, and only the fields the file contains: a due date you set here afterwards is not wiped by a column the export left empty.
If the file has no issue key, that is warned about — without one, importing twice would create everything twice.
One bad row does not abandon the rest
A row with no title is skipped and counted. A row with an unparseable date keeps everything else. Up to a hundred per-row notes are kept and shown under the import; a 5000-row file with 5000 warnings is not a report anybody reads.
Two things to know before a large import
A queue worker must handle the imports lane:
php artisan queue:work redis --queue=broadcasts,mail,webhooks,imports,default
Files are capped at 20 MB and 20,000 rows. Export in batches above that — a
single import that large is worth doing in pieces anyway, and the imports table
records each one.
The file is deleted from our disk as soon as it has been read. It was somebody's whole issue tracker.
Not there yet
- No comments. A Jira export repeats a
Commentcolumn per comment, and parsing that reliably is a separate piece of work rather than a line in this one. - No attachments. Félagi stores files, but a CSV export does not contain them — it contains filenames on somebody else's server, behind somebody else's authentication. Fetching those would mean holding a credential for the tool you are leaving.
- No API pull. File export only, which is deliberate for now: pulling from four vendors means storing four kinds of customer credential on a server whose whole argument is that it holds no keys.
- No cycles. A window in Jira is a sprint somebody opened on a date that is not in the export. Félagi's cycles are generated on a cadence, so there is nothing to map an arriving sprint name onto without inventing the dates.
- No undo. There is no "delete this import" button; issues arrive as issues. The dry run exists so that matters less.
- One level of nesting. An epic inside an epic is left at the top level and reported.