プロジェクト管理ツール「Linear」に他サービスから課題をインポートする

最近 「Linear」 というプロジェクト管理ツールを人から教えていただきました。

- 公式サイト
    - [https://linear.app](https://linear.app)
- 参考）紹介記事
    - [エンジニアが作る、エンジニアが“使いたがる”タスク管理ソフトウェアLinear - TECHBLITZ](https://techblitz.com/linear/)

以下、上記ページから引用

> Linearは、AsanaやTrelloなどの、タスクをチームメンバーに割り当て、その進捗状況を管理するためのツールと、Jiraのような、ソフトウェア開発プロジェクトの中期計画、追跡、管理を実行できる多機能ツールの中間的な存在となることを目指しています。

まさに「AsanaやTrelloだと物足りない」「Jiraだと仰々しすぎる」と感じていた私にピッタリかもしれない、と思って使い始めました。

インポート可能なサービスは執筆時点で以下の通りです。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/104653/5014527b-9e2c-6997-4d69-f1aea12e5ac9.png)

今回は、Jiraからインポートしました。

# 準備

## Dockerfileの作成

Linearに課題をインポートするには、公式が用意している以下ツールを使用します。

https://github.com/linearapp/linear-import

環境を汚したくなかったので、実行用のDockerfileを作成しました。

- インポートツールが NodeJs 14.x 以上で実行されるため、NodeJsイメージを使用しています。

```dockerfile
# Use nodejs 15.x offcial image
FROM node:15-alpine

RUN apk update && \
    apk add --no-cache \
    bash \
    curl \
    gnupg

# Install yarn
# https://github.com/linearapp/linear-import/issues/50
RUN touch ~/.bashrc \
    && curl -o- -L https://yarnpkg.com/install.sh | bash

# Install Linear Import tool
RUN npm i -g @linear/import

# Copy file
COPY ./Jira.csv /tmp/Jira.csv
```

- 2021/01/08追記: ビルド済みイメージをDockerHubにアップしました。
    - [ushibutatory/linear-import - DockerHub](https://hub.docker.com/r/ushibutatory/linear-import)

## Jiraから課題をエクスポート（CSV形式でダウンロード）

[Filters]から移行したい課題をリストアップして、[Export]-[Export Excel CSV(all fields)]を実行します。

### 注意！

LinearのインポートツールはCSV項目名を英語で判別しているらしく、日本語でエクスポートしたCSVだと後々のインポート実行時でエラーになります。

Jira側の環境設定で言語を英語に切り替えてからエクスポートしましょう。

## フォルダ構成

以下のようにしました。
※フォルダ名 `linear` はお好みで。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/104653/94fec716-6b78-ad1d-40e3-cc33930874fa.png)

# 移行の実施

## Dockerイメージのビルドと起動

```console
> cd linear
> docker build -t linear-import:latest .
> docker run -t -i linear-import /bin/bash
```

ビルド時に `npm i -g @linear/import` で色々 deprecated なパッケージの警告が出ますが、こちらではどうしようもないので無視しました。

あとは `linear-import` コマンドを実行し、順次オプションを入力・選択していきます。

- API Key: 書かれているURL、またはLinear画面のプロフィールから[Settings]-[Account]-[API]内のPersonal API Keysで新規にgenerateしたものを使用します。
    - 移行が完了したら削除してOK

```bash
root@20849d606d70:/# linear-import
? Input your Linear API key (https://linear.app/settings/api) XXXXXXXXX
? Which service would you like to import from? Jira (CSV export) # Jiraを選択
? Select your exported CSV file of Jira issues tmp/Jira.csv # ファイルを選択
? Input the URL of your Jira installation (e.g. https://acme.atlassian.net): https://xxx.atlassian.net/ # JiraのURLをペースト
? Do you want to create a new team for imported issues? Yes # お好みで
? Name of the team: Jira # お好みで
? Do you want to assign these issues to yourself? Yes # お好みで
Jira (CSV) issues imported to your backlog: ...
```

エラーが起きなければ完了です。

### エラー例

インポートでエラーが発生した場合は、メッセージを読めばおおよそ原因は分かります。
（かなり親切にエラーメッセージを返してくれる印象）

例）CSV形式が正しくない場合のエラー

前述の通り、Jiraを日本語で使っている場合はエクスポートされるCSVの項目名も日本語で出力されるため、Linearではインポートできません。

```bash
ClientError: Variable "$title" of required type "String!" was not provided.: {
    "response": {
        "errors": [
            {
                "message": "Variable \"$title\" of required type \"String!\" was not provided.",
                "locations": [ ... ]
            }
        ],
        "status": 400
    },
    "request": {" ...
```

例）上記で入力したチーム名が既に存在している場合のエラー

```bash
Error occurred while importing:
{
  "errors": [
    {
      "message": "duplicate team name",
      "path": [
        "teamCreate"
      ],
      "locations": [ ... ],
      "extensions": {
        "type": "invalid input",
        "userError": true,
        "userPresentableMessage": "Team with this name already exists"
      }
    }
  ],
  "data": null
}
```

まだリリースされた直後のサービスなので、これからのアップデートが楽しみです。

不備などあればご指摘ください。