10 · Bring your work in from ClickUp
What you will have done: copied a ClickUp workspace into Neutron as projects, sprints, epics and items, checked the result, and run the whole thing a second time without doing any damage.
What this is, and who can run it
This is a one-shot import, not a synchronisation. It reads a ClickUp workspace and writes projects and items into Neutron. Afterwards the two are separate: nothing flows either way.
Only somebody who administers the whole instance can run it, and it is run through the instance’s programmatic interface rather than from a screen. There is no import button in the app. The reason is the credential: the import needs a ClickUp token that can read the entire workspace, and there is no smaller version of that to hand to anybody else.
What becomes what
| In ClickUp | In Neutron |
|---|---|
| A space | A project under your organisation |
| A folder of sprint lists | A sprint each, named for the week it ran |
| A backlog folder’s lists | The Backlog and Ready columns |
| A task tagged as an epic | An epic, with its subtasks as children |
| Task statuses | The seven-state spine: to do → backlog, in progress → in progress, review → in review, approved and complete → done, postponed → cancelled with a postponed label |
| Tags | Labels on the project |
| Assignees | People, matched by email address |
| “GitLab neutron#760” in a description | Reported as a code-host reference, to be applied in a second step |
The walkthrough
1. Do a dry run first
The import takes a ClickUp team identifier, a token, and optionally the organisation to put the projects under. Ask for a dry run first: it reads everything, works out what it would create, and writes nothing.
Read the report. It says how many projects, sprints and items it found, and it warns about anything it is going to skip.
2. Run it
Run the same request without the dry run. It creates the projects, the sprints, the labels and the items, and reports what it made.
3. Check the count
Compare the number of items it reports against the number of tasks in the workspace. They should be equal. If they are not, the report says which ones it skipped and why.
4. Run it again
This is the important step, and it is safe. Every imported item remembers the ClickUp task it came from, so a second run finds the existing rows rather than making new ones. It should report the same number and change nothing.
5. Give each project a key
The import creates the projects without one, so their cards have no short name. Open each imported project’s Settings, set its reference key, and every card it imported is numbered from that moment, oldest first. Do this before the next step: a merged change can then name a card by its reference rather than only by the issue it links to.
6. Apply the code-host references
The import notices addresses like neutron#760 inside task descriptions and reports them, but it does not link them. A second, separate request per project applies those links wherever exactly one repository answers to the name. It also takes a dry run.
7. Work in Neutron for a week
Leave the ClickUp workspace read-only by agreement for one sprint. Anything you find that differs is an import problem: fix it and re-run, which is safe. When the week ends without surprises, archive the ClickUp workspace.
A worked example
The team that built Neutron moved their own work in. Their workspace had four spaces and 124 tasks.
- A dry run reported four projects and 124 tasks, and warned about two sprint lists that were empty.
- The real run created 124 items across the four projects, 18 labels, and two sprints named for the week they ran. The two empty sprint lists were skipped, and the tasks that would have gone in them arrived without a sprint rather than being dropped.
- It reported 51 code-host references found in descriptions.
- A second run reported 124 unchanged.
- The reference-applying step linked 49 of the 51. The other two were second references on items that already held one, and an item holds one link.
What can go wrong
| The sentence you get back | What happened, and what to do |
|---|---|
| forbidden | You are not an administrator of the instance, or the token you are calling with is not one. Only an instance administrator can run this. |
| team_id is required | The ClickUp team identifier is missing or has characters it should not. |
| org_id is invalid | The organisation identifier does not look like one. Take it from the org chart. |
| dry_run must be a boolean | It is true or false, not a word. |
| A sprint list was skipped | The list was empty, or a sprint of that name already exists. Its tasks are imported without a sprint. Put them in one by hand. |
| Every imported card shows a piece of an id rather than a short name | The project has no reference key. Set one on Settings › Reference key and every imported card is numbered. |
| A merged change does not close an imported item | Either the project has no reference key yet, or the change names neither the reference nor the linked issue. |
Confirm it worked: the projects appear in the middle column with the counts you expect, and a second run of the same import reports the same numbers and changes nothing.