> ## Documentation Index
> Fetch the complete documentation index at: https://docs.diversion.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Perforce からのインポート

> Perforce の depot を履歴ごと新しい Diversion リポジトリにインポートする方法

Perforce の depot を、履歴を含めて新しい Diversion リポジトリにインポートできます。
インポートはお客様が用意するマシン(**インポート用マシン**)上で実行され、そのマシンは Perforce サーバーにネットワーク接続できる必要があります。
Perforce のパスワードはインポート用マシンに残り、Diversion に送られることはありません。

Diversion アプリがリポジトリと API トークンを作成し、インポート用マシンに必要な設定ファイルを生成します。
その後、インポート用マシン上のスクリプトが Docker でインポートを実行し、5 分ごとに Diversion と通信します。

<Note>
  ご自身でインポートを実行できない場合(Windows マシンしかない場合など)は、代わりに[マネージドインポートを依頼](#マネージドインポートを依頼する)してください。
</Note>

## インポート用マシンの要件

* `bash` と `cron` のある Unix マシン
* Docker Engine 20.10 以降と Docker Compose プラグイン 2.17 以降
* Perforce サーバー、および HTTPS で Diversion へのネットワーク接続
* 任意: `curl` と AWS CLI。ない場合、スクリプトはコンテナイメージから実行します。

## Diversion アプリでインポートを設定する

<Steps>
  <Step title="Perforce インポートページを開く">
    Diversion アプリで **New repository** をクリックし、**Import from P4** を選択します。パンくずリストのリポジトリメニュー下部にある **Import from Perforce** を選択することもできます。

    <img src="https://mintcdn.com/diversion-2/1TVJoD7AdabMtZcG/images/p4-import/new-repository-menu.png?fit=max&auto=format&n=1TVJoD7AdabMtZcG&q=85&s=c4cffbe2666cb9ca86b069f931d8f688" alt="Import from P4 が表示された New repository メニュー" style={{width: 'auto', maxWidth: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} width="359" height="156" data-path="images/p4-import/new-repository-menu.png" />

    <Note>セルフホスト環境では、**Import from P4** をクリックすると代わりにリクエストフォームが開き、Diversion チームがインポートを代行します。</Note>
  </Step>

  <Step title="インポートスクリプトをダウンロードする">
    **Download p4\_import\_bootstrap.sh** をクリックします。スクリプトはすべてのインポートで共通で、このページからいつでもダウンロードできます。
  </Step>

  <Step title="新しいリポジトリに名前を付ける">
    リポジトリ名は depot 名から自動入力されます。必要に応じて変更してください。
    リポジトリは組織に属している必要があります。組織がまだない場合は、ここで作成できます。
  </Step>

  <Step title="インポート設定を入力する">
    各欄の意味は下の[インポート設定](#インポート設定)を参照してください。

    <img src="https://mintcdn.com/diversion-2/1TVJoD7AdabMtZcG/images/p4-import/import-form.png?fit=max&auto=format&n=1TVJoD7AdabMtZcG&q=85&s=44e0b8aa1c9ffeb2578ae3813f4ed3a9" alt="リポジトリとインポート設定が入力された Import from Perforce ページ" style={{width: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} width="1007" height="1214" data-path="images/p4-import/import-form.png" />
  </Step>

  <Step title="「Create repository and import files」をクリックする">
    Diversion がリポジトリ、API トークン、インポート設定を作成します。
  </Step>

  <Step title="local.env をダウンロードする">
    **Download local.env** をクリックします。このファイルには API トークン、リポジトリ ID、セットアップ手順が含まれています。

    <img src="https://mintcdn.com/diversion-2/1TVJoD7AdabMtZcG/images/p4-import/import-result.png?fit=max&auto=format&n=1TVJoD7AdabMtZcG&q=85&s=4f79aecd2e6b9f5772bc65116c6fad0f" alt="API トークン、Download local.env ボタン、インポート用マシンのセットアップ手順" style={{width: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} width="1003" height="1146" data-path="images/p4-import/import-result.png" />

    <Warning>
      API トークンは一度しか表示されません。ページを離れる前に `local.env` をダウンロードしてください。ダウンロードせずに離れてしまった場合は、[失った local.env を復元する](#失った-local-env-を復元する)を参照してください。
    </Warning>
  </Step>
</Steps>

### インポート設定

| 欄 | 内容 |
| - | - |
| **Depot to import** | `//depot/...` の形式で指定する depot 全体です。スペース・`#`・`@` は使えません。一部のブランチだけをインポートするには **Branches to import** を使います。 |
| **Depot type** | ブランチがストリームの場合は **Stream depot**、ブランチをパスで定義している場合は **Local (classic) depot** を選びます。 |
| **Branch name depth** | ローカル depot で、**Branches to import** が空の場合のみ使われます。空にすると、depot の branch spec からブランチを探します。数値を入れると、depot のルートからその深さにある各フォルダーがブランチになります。`1` なら `//depot/main/...` がブランチ `main`、`2` なら `//depot/dev/feature/...` がブランチ `dev/feature` です。`0` にすると depot 全体を 1 つのブランチとしてインポートします。 |
| **Is there more than one mainline in the depot?** | 1 つの Diversion リポジトリには 1 つのメインラインとその子孫が入ります。depot に複数ある場合は **Yes** を選び、インポートするものを **Mainline branch** に入力します。他のメインラインにはそれぞれ別のリポジトリが必要です。 |
| **Branches to import** | 任意。スペースを含まないカンマ区切りのブランチ名です(例: `main,dev`)。すべての名前は同じ深さである必要があります。空にするとすべてのブランチをインポートします。 |
| **Path to exclude** | 任意。`//depot/builds/` のような depot パスの接頭辞です。その下のファイルはインポートされません。 |

## local.env を保護する

`local.env` には、**Diversion アカウントへの管理者権限**を持つ API トークンが含まれています。
パスワードと同じように扱ってください:

* インポート用マシンだけに置き、インポートを実行するユーザーだけが読めるようにします(下の手順の `chmod 600 local.env`)。
* バージョン管理にコミットしたり、チャットやメールで共有したり、他のマシンにコピーしたりしないでください。

## インポート用マシンでインポートを実行する

以下の手順は、インポートを実行するユーザー(Docker を使えるユーザー)で行ってください。`sudo` は使わないでください。root の crontab にスケジュールが登録されてしまいます。

<Steps>
  <Step title="両方のファイルを同じディレクトリに置く">
    `p4_import_bootstrap.sh` と `local.env` をインポート用マシンの同じディレクトリ(例: `/opt/dv-p4-import`)にコピーし、そのディレクトリに `cd` します。
  </Step>

  <Step title="スクリプトを実行可能にする">
    ```bash theme={null}
    chmod +x p4_import_bootstrap.sh
    ```
  </Step>

  <Step title="Perforce の設定を入力する">
    `local.env` を開き、ファイル末尾の Perforce 接続情報を入力します:

    ```bash theme={null}
    P4PORT=perforce.example.com:1666
    P4USER=import-user
    P4PASSWD=...
    ```

    `API_DOMAIN`、`API_TOKEN`、`REPO_ID` は生成されたままにしてください。
  </Step>

  <Step title="local.env を保護する">
    ```bash theme={null}
    chmod 600 local.env
    ```
  </Step>

  <Step title="スクリプトを一度実行して設定を確認する">
    ```bash theme={null}
    ./p4_import_bootstrap.sh
    ```

    初回の実行が成功すると、インポート設定をダウンロードし、Diversion のインポートイメージを取得して起動します。
    出力には `Remote env changed -- recreating: ...` のような行が表示され、`docker ps` でインポートコンテナが動作していることを確認できます。
    初回はイメージのダウンロードのため数分かかることがあります。
  </Step>

  <Step title="インポートをスケジュールする">
    ```bash theme={null}
    ./p4_import_bootstrap.sh --install-cron
    ```

    このディレクトリからスクリプトを 5 分ごとに実行し、出力を `bootstrap.log` に追記する crontab エントリを追加します。
    実行のたびに、停止したインポートを再起動し、設定の変更を反映します。
  </Step>
</Steps>

## インポートの進行状況を確認する

Diversion で新しいリポジトリを開きます。インポートが完了するまで、リポジトリページに **Reading history**、**Preparing history**、**Uploading files** の 3 段階で進行状況が表示されます。
履歴の準備ができると、コミット、ブランチ、ファイルが表示されます。ファイルは内容のアップロード後に開けます。

大きな depot のインポートには時間がかかります。完了するまで、インポート用マシンを起動したまま接続しておいてください。

## インポートを停止・削除する

crontab エントリを削除するまで、インポートは動作し続けます。

<Note>
  初回インポートの後も Perforce からの継続的なインポートや Perforce へのエクスポートが必要な場合は、crontab エントリを削除しないでください。継続的なインポート・エクスポートを有効にするには[サポートにお問い合わせください](mailto:support@diversion.dev)。
</Note>

インポートが完了し、継続する必要がない場合:

1. `crontab -e` を実行し、`p4_import_bootstrap.sh` を含む行を削除します。
2. インポート用マシンから `local.env` を削除します。

## トラブルシューティング

スクリプトはエラーを出力に書き込み、スケジュール後はインポート用ディレクトリの `bootstrap.log` にも書き込みます。

| メッセージ・症状 | 対処 |
| - | - |
| `Local config not found at ./local.env` | `local.env` があるディレクトリからスクリプトを実行してください。 |
| `Missing required variable in ./local.env: ...` | `local.env` に表示された値を入力してください。 |
| `API_TOKEN must be an API token from the account page (starts with dvk_)` | `API_TOKEN` が変更されたか途中で切れています。生成された値に戻してください。 |
| `docker compose >= 2.17 required` | Docker Engine 20.10 以降と Docker Compose プラグイン 2.17 以降にアップグレードしてください。 |
| `crontab already has a p4_import_bootstrap.sh entry` | インポートは既にスケジュールされています。別のディレクトリに移す場合は、先に `crontab -e` で古いエントリを削除してください。 |
| `... returned HTTP 401` | API トークンが失効しているか無効です。修正するまでインポートは停止します。[新しいトークンを生成](/ja/ci-cd#api-トークンを生成する)し、`local.env` の `API_TOKEN` を置き換えてください。 |
| `... returned HTTP 403` | トークンのユーザーがリポジトリの管理者権限を失っています。権限が戻るまでインポートは停止します。 |
| `... returned HTTP 404` | `local.env` の `REPO_ID` がリポジトリと一致しているか確認してください。一致している場合はサポートにお問い合わせください。 |
| `... did not include an ETag` | プロキシなど、ネットワーク上の何かがレスポンスヘッダーを削除しています。プロキシの設定を確認するか、サポートにお問い合わせください。 |
| `Another bootstrap run is in progress -- skipping this tick` | 初回のイメージのダウンロード中など、時々発生するのは正常です。何時間も続く場合は、`bootstrap.log` で止まっている実行がないか確認してください。 |
| インポートページに **This repository already has an import configuration** と表示される | このリポジトリの設定はページから変更できません。変更するにはサポートにお問い合わせください。 |
| リポジトリページが **Waiting for the import to start** のまま | crontab エントリがあること(`crontab -l`)と、`bootstrap.log` にエラーがないことを確認してください。 |
| **No progress in 30 min** | 大きな depot ではここで一時停止することがあります。続く場合は、インポート用マシンが動作しており、インポートコンテナが起動していること(`docker ps`)を確認してください。 |
| **Import stopped** | インポート用マシンが動作していることを確認し、`docker logs` でコンテナの出力を確認してください。インポートが再開しない場合はサポートにお問い合わせください。 |

### 失った local.env を復元する

`local.env` をダウンロードする前に **Import from Perforce** ページを離れてしまった場合は、新しいインポートを始めないでください。リポジトリとインポート設定は既に作成されています。代わりにファイルを作り直してください。

<Steps>
  <Step title="local.env を作成する">
    インポート用マシンで、`p4_import_bootstrap.sh` と同じディレクトリに次の内容で `local.env` を作成します:

    ```bash local.env theme={null}
    # Generated by the Diversion web app. Setup steps, in order:
    #   1. Put this file next to p4_import_bootstrap.sh on the import host.
    #   2. Make the script executable:            chmod +x p4_import_bootstrap.sh
    #   3. Fill in the Perforce settings below.
    #   4. Protect this file:                     chmod 600 local.env
    #   5. Check the setup, once:                 ./p4_import_bootstrap.sh
    #   6. Install the import (every 5 minutes):  ./p4_import_bootstrap.sh --install-cron
    #
    # To remove it later, run `crontab -e` and delete the p4_import_bootstrap.sh line.
    # To stop it for good, also revoke the API token below, under Settings > Integrations.
    API_DOMAIN=https://api.diversion.dev
    API_TOKEN=
    REPO_ID=

    # Perforce connection. The password stays on this host; Diversion never sees it.
    P4PORT=
    P4USER=
    P4PASSWD=
    ```
  </Step>

  <Step title="REPO_ID を入力する">
    Diversion アプリでパンくずリストのリポジトリ名をクリックすると、組織内のリポジトリ一覧が開きます。新しいリポジトリの行にマウスを重ね、表示される **Copy repo ID** ボタンをクリックします。コピーした ID を `REPO_ID` に貼り付けます。

    <img src="https://mintcdn.com/diversion-2/1TVJoD7AdabMtZcG/images/p4-import/copy-repo-id.png?fit=max&auto=format&n=1TVJoD7AdabMtZcG&q=85&s=76930bb8ced0bb5c471c1fc253deca97" alt="Copy repo ID ボタンが表示されたパンくずリストのリポジトリメニュー" style={{width: 'auto', maxWidth: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} width="514" height="362" data-path="images/p4-import/copy-repo-id.png" />
  </Step>

  <Step title="API_TOKEN を入力する">
    インポートページでトークンをコピーしていた場合は、`API_TOKEN` に貼り付けます。

    コピーしていない場合は、新しいトークンを生成します:

    1. 右上のアバターをクリックし、メニューから **Integrations** を選択します。
    2. **Generate a new API token** をクリックし、名前を入力して **Generate token** をクリックします。トークンがリポジトリへの管理者権限を持つよう、リポジトリを作成したユーザーでサインインした状態で生成してください。
    3. トークンをコピーし、`API_TOKEN` に貼り付けます。トークンは一度しか表示されません。

    <img src="https://mintcdn.com/diversion-2/1TVJoD7AdabMtZcG/images/p4-import/integrations-token.png?fit=max&auto=format&n=1TVJoD7AdabMtZcG&q=85&s=43883eda778ca33081baeb47ab200183" alt="Generate a new API token ボタンが表示された Integrations ページ" style={{width: '90%', borderRadius: '1.5rem', border: '.3rem solid #555', boxShadow: '0 0 1rem #888' }} width="1034" height="225" data-path="images/p4-import/integrations-token.png" />
  </Step>

  <Step title="セットアップを続ける">
    [インポート用マシンでインポートを実行する](#インポート用マシンでインポートを実行する)を最初から行ってください。
  </Step>
</Steps>

## マネージドインポートを依頼する

上記の要件を満たせない場合は、Diversion がインポートを代行します。**Import from Perforce** ページ下部の **Request a managed import** を使うか、[support@diversion.dev](mailto:support@diversion.dev) までお問い合わせください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.