# クイックスタート {#quickstart}

このページでは、Takumi Runner の導入から最初のワークフロー実行までの手順を説明します。

## 前提条件 {#prerequisites}

Takumi Runner を利用するには、以下の条件を満たしている必要があります。

- Shisho Cloud の組織と、それに所属するユーザーを持っていること
- 連携する GitHub Organization とその管理者権限を持っていること
- Takumi サブスクリプションが有効であること
- 初期設定（Runner 機能の有効化や GitHub App のインストールなど）を行うユーザーが、Shisho Cloud 上で **Takumiの管理者**ロールと **API連携の管理者**ロールを持っていること
- ダッシュボードやジョブ実行履歴の確認を行うユーザーが、Shisho Cloud 上で **Takumi Runnerの利用者**ロールを持っていること

:::info
**パブリックリポジトリ**での利用には、GitHub Organization のランナーグループ設定（**Settings** > **Actions** > **Runner groups**）で **Allow public repositories** を有効にする必要があります。この設定はデフォルトで無効なため、Takumi Runner のセットアップ時にあわせて確認・変更してください。無効のままだと、ジョブが `queued` のまま開始されません。詳しくは[公式ドキュメント](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/managing-access-to-self-hosted-runners-using-groups)をご覧ください。組織外のコントリビューターがトリガーしたワークフロー実行も課金対象となる点にご注意ください。
:::

## 手順 {#steps}

### 1. Runner 機能を有効にする {#enable-runner}

Shisho Cloud コンソールのサイドバーから **Runner** を開き、**セットアップ**タブに進みます。セットアップウィザードが表示されますので、最初のステップで **Runner 機能を有効にする** を完了してください。

![Runner セットアップウィザード](/docs/ja/_md-assets/89a95f2709-setup-wizard.png)

### 2. GitHub App をインストールする {#install-github-app}

続いて、セットアップウィザードの次のステップで **GitHub App をインストール** ボタンをクリックしてください。GitHub のインストール画面に遷移します。

1. Runner を有効にする対象を選択してください
   - **All repositories** を選ぶとすべてのリポジトリで利用できる
   - **Only select repositories** を選ぶと特定のリポジトリのみ有効になる
2. **Install** をクリックしてインストールを完了してください

:::info
GitHub App のインストールには、GitHub Organization の **Owner** 権限が必要です。権限がない場合は、Organization の管理者にインストールをリクエストしてください。管理者による承認後、Shisho Cloud コンソールの **設定** > **サービス連携** > **CI/CD 連携** セクション内にある GitHub Actions の連携カードから、**既存の GitHub App を連携** を選択してインストールできます。
:::

GitHub App が取得するアクセス権限の詳細は [GitHub 連携 > GitHub App の権限](/docs/ja/t/runner/architecture/integration.md#permissions) をご覧ください。

### 3. ワークフローファイルを編集する {#edit-workflow}

既存のワークフローファイル（`.github/workflows/*.yml`）の `runs-on` を `takumi-runner` に変更します。

```yaml
jobs:
  build:
    runs-on: takumi-runner
    steps:
      - uses: actions/checkout@v4
      - run: npm install
      - run: npm test
```

### 4. ワークフローを実行する {#run-workflow}

コードをプッシュするか、GitHub 上で手動実行してワークフローをトリガーしてください。Takumi Runner が自動的にジョブを受け取り、セキュアな VM 上で実行します。

### 5. トレースを確認する {#check-traces}

ワークフローの実行が完了すると、Shisho Cloud コンソールの **Runner** > **ジョブ**タブにジョブの実行履歴が表示されます。

![ジョブ一覧](/docs/ja/_md-assets/cb59957231-jobs-list.png)

ジョブをクリックすると、概要画面でプロセス実行・ネットワーク通信・ファイルアクセスの一覧を確認できます。

![ジョブ概要](/docs/ja/_md-assets/3e444a586b-job-overview.png)

**タイムライン**タブでは、ワークフローの各ステップとそのトレースを確認できます。

![ジョブタイムライン](/docs/ja/_md-assets/df92b4d670-job-timeline.png)

## 次のステップ {#next-steps}

- トレースデータの詳細は [トレースの取得](/docs/ja/t/runner/features/trace-collection.md) をご覧ください
- 実行履歴の確認は [ジョブ実行履歴](/docs/ja/t/runner/observability/job-history.md) をご覧ください