KATATANDocs
ENJA
アプリを開く ›
Docs/Feature/Project/Git管理モード
748 語 · 約 4 分

Git管理モード

Git管理モードは、テスト仕様書を開発コードと同じ GitHub リポジトリで管理するためのプロジェクトの管理方法です。仕様書の変更は、コードと同じブランチ・同じプルリクエスト（PR）でレビューできます。テストの実施と結果の共有は、これまでどおり KATATAN で行います。

DB管理モードとの違い

項目 DB管理モード Git管理モード
テスト仕様書の保存先 KATATAN GitHub リポジトリの CSV ファイル
保存 自動保存 保存 = commit（commit メッセージを入力）
変更のレビュー KATATAN の変更履歴 GitHub の PR
テストレポートの保存先 KATATAN KATATAN（Git には保存しない）
仕様書・テストケースの MCP ツール / CLI コマンド 利用可能 利用不可（リポジトリの CSV を直接編集する）

向いている使い方

  • 機能の追加と、そのテスト仕様書の追加を、同じブランチ・同じ PR でレビューしたい
  • 「コードは更新したのに、テスト仕様書が古いまま」という状態を防ぎたい
  • Git に慣れていないメンバー（QA・PM など）も、ブラウザだけで仕様書の編集に参加させたい

用語

用語 意味
リポジトリ GitHub 上の、ファイルの置き場所
ブランチ リポジトリの中の、作業の流れ（版の系列）。例: main、develop
commit 変更を1つの区切りとして保存すること。Git管理モードでの「保存」
PR（プルリクエスト） ブランチの変更を、別のブランチに取り込んでもらうための依頼。GitHub でレビューする
保護ブランチ GitHub で直接の変更が禁止されているブランチ。KATATAN では読み取り専用で開く
作業ブランチ KATATAN の「編集を開始」で作る、自分用のブランチ。名前は katatan/spec/<ユーザー名>/<名前>
KATATAN 形式の CSV 列が No, Labels, Test Subject, Preconditions, Steps, Expected Result, Notes, Images の CSV。KATATAN の CSV エクスポートと互換
スナップショット レポートを作った時点の仕様書の内容のコピー。仕様書が後で変わっても、レポートの内容は変わらない

Git管理モードのプロジェクトを作る

  1. プロジェクトの作成ダイアログの「テスト仕様書の管理方法」で、「Git管理」を選びます。
  2. 「リポジトリURL」に GitHub のリポジトリの URL を入力します（例: https://github.com/owner/repo）。
  3. 「リポジトリを連携」を押します。ポップアップで GitHub の画面が開くので、KATATAN GitHub App のインストールと許可を行います。
    • GitHub で保存しても KATATAN の画面が戻らないときは「続ける」を押します。
  4. 「{リポジトリ} と連携しました（デフォルトブランチ: {ブランチ}）」と表示されたら、プロジェクトを作成します。

管理方法は、プロジェクトを作成した後には変更できません。

連携先の変更・再連携

プロジェクト設定の「リポジトリ」で、連携するリポジトリの変更や再連携を行えます（プロジェクトOwner・ワークスペースOwnerのみ）。連携先を変更しても、作成済みのテストレポートは残ります。

GitHub にログインする

リポジトリの中身は、操作する人本人の GitHub アカウントの権限 で表示・編集します。そのため、各メンバーが一度「GitHub にログイン」する必要があります。初めてリポジトリを開いたときに「GitHub にログインしてリポジトリを表示」と表示されます。

  • KATATAN に「GitHub でログイン」している人も、別に GitHub での許可が必要です。 KATATAN へのログインと、リポジトリへのアクセスの許可は、GitHub 上で別の手続きです。
  • アカウント設定（プロフィール）の「GitHub の連携」で、連携している GitHub のログイン名の確認・連携・解除ができます。
  • 許可は自動で更新されます（8時間ごと）。6か月使わなかった場合や、GitHub 側で許可を取り消した場合は、もう一度ログインが必要です。
  • GitHub で設定したアクセス制御（チームの権限、組織からの除外、SAML SSO など）は、KATATAN でもそのまま適用されます。KATATAN のサーバーがリポジトリを丸ごと複製（clone）することはありません。

リポジトリを見る

サイドバーには、プロジェクトのリポジトリ名（GitHub へのリンク）、ブランチの切り替え、ルートのファイルとフォルダが表示されます。その下の「KATATAN のレポート」の見出しにある「テストレポート」から、レポートの一覧を開けます。

ファイルを選ぶと、メインエリアに次のように表示されます。

ファイル 表示
フォルダ 中身の一覧。README.md があれば下に表示
CSV / TSV 表エディタ（CSV4TEST）で開く
Markdown 整形して表示
画像（png / jpg / gif / webp / svg） 画像として表示
テキスト・コード そのまま表示（1MB を超える場合は先頭の 1MB のみ）
その他 「このファイルはプレビューできません」と表示し、「ダウンロード」「GitHubで開く」を提示
  • ブランチの切り替え: ブランチの選択はユーザーごとです（ほかの人の表示には影響しません）。URL を共有すれば、同じブランチを開けます。自分の作業ブランチは「自分の作業ブランチ」としてまとめて表示されます。
  • 再読み込み: GitHub 側の変更（ほかの人の push など）は自動では反映されません。ファイルを開き直すか、「再読み込み」を押すと最新の内容になります。
  • 開いていたブランチが削除された場合（PR のマージで自動削除された場合など）は「ブランチ「〜」が見つかりません。PR のマージで削除された可能性があります。」と表示され、「デフォルトブランチ（〜）に切り替える」で戻れます。

テスト仕様書を編集する

KATATAN で編集できるのは CSV と TSV のみ です（ほかのファイルは閲覧のみ）。

保存と commit

保存ボタン（または Ctrl+S）を押すと、commit メッセージを入力するダイアログが表示され、確定すると1つの commit になります。

  • commit の作成者は、KATATAN のユーザーの名前とメールアドレスになります。
  • 画像（Images 列）を追加すると、<CSV名>.assets/ フォルダに一緒に commit されます。
  • 未保存の変更はブラウザに下書きとして残ります（タブを閉じても失われません）。画面を離れようとすると確認が表示されます。

編集を開始・PR を作成

  • デフォルトブランチ・保護ブランチ は読み取り専用で開きます。「編集を開始」を押すと、自分用の作業ブランチを作成してそこで編集できます。
  • 作業ブランチでは「PRを作成」で、元のブランチに向けた PR を作成できます。PR の状態（オープン・マージ済み・クローズ）も表示されます。
  • 保護されていないブランチには、そのまま直接 commit できます。

新しいテスト仕様書

フォルダの画面の「新しいテスト仕様書」で、KATATAN 形式の見出し行だけを持つ CSV を作成できます。

競合したとき

ほかの人が先に同じファイルを commit していた場合は「ほかの人が先に同じファイルを commit しています。」と表示され、内容を確認して保存し直せます。違うファイルへの変更は、自動で積み上がります。

テストを実施する

  1. CSV を開き、ヘッダーの「このファイルでテストを開始」を押します（プロジェクトの Editor 以上で、GitHub の読み取り権限がある人に表示されます）。
  2. ダイアログで報告書名と、完了時に呼ぶ Webhook（任意）を選び、「テスト開始」を押します。

選択中のブランチの最新の内容を取り込んでテストレポートを作成します。リポジトリには何も commit しません。

  • 作成したレポートは、サイドバーの「テストレポート」から一覧で開けます（GitHub にログインしていなくても開けます）。
  • 結果の入力、自動完了、中断・再開・強制完了、共有リンク、CSV エクスポート、Webhook は、DB管理モードのレポートと同じです（Test report 参照）。
  • レポートの詳細には「取り込み元」（ファイル・ブランチ・commit）が表示されます。ファイル名から、リポジトリのそのファイルを開けます。

仕様書が更新されたとき

レポートを作成した後で仕様書が更新されると、「このレポートを作った後に、仕様書が更新されています」と表示され、「GitHub で差分を見る」で変更点を確認できます。

  • 取り込み元のファイルが移動・削除された場合は「取り込み元のファイルが見つかりません」、ブランチが削除された場合は「取り込み元のブランチ「〜」が見つかりません」と表示されます。
  • この表示は、見る人の GitHub の読み取り権限で確認します。GitHub にログインしていない人には表示されません。
  • レポートの内容（取り込んだ仕様書のスナップショット）は、仕様書が更新されても変わりません。

取り込めない CSV・画像

  • KATATAN 形式でない CSV、No が数字でない・重複している CSV、テストケースがない CSV は、理由を表示してレポートを作成しません。
  • 画像（Images 列）は PNG と JPEG を取り込みます。見つからない・形式が違う・5MB を超える画像は取り込まず、「取り込めなかった画像があります（N 件）」と表示します（レポート自体は作成されます）。

CLI で使う

@katatan/cli の 0.2.0 以降で、手元の CSV からテストレポートを作成できます（コマンドの詳細は KATATAN CLI 参照）。

# 手元の CSV からテストレポートを作る
katatan report create --spec ./specs/login.csv --name "回帰テスト 2026-10"

# レポートを CSV に書き出す（書き出すだけで、KATATAN とは同期しない）
katatan report export <レポートID> --out ./report.csv
  • report create は、CSV の中身と Git の情報（現在の commit・ブランチ・リポジトリ内のパス・未 commit の変更の有無）を送信します。
    • 未 commit の変更があるときは警告を表示します。 レポートには「未commitの変更を含む」と表示されます。
    • ブランチを checkout していない状態（detached HEAD）では、--branch でブランチ名を指定します。
    • 画像は <CSV名>.assets/ フォルダの PNG・JPEG を、合計 3MB まで送信します。
  • 既存の MCP アクセストークンでは使えません。 プロジェクト設定の「MCP Access Control」でトークンを編集し、create_git_report と export_test_report を許可してください。
  • Git管理モードのレポート ID は {プロジェクトID}.git.{レポートID} の形式です（画面の「ID をコピー」でこの形式がコピーされます）。
  • Git管理モードのプロジェクトでは、仕様書・テストケースを扱う MCP ツールと CLI コマンドはエラー（spec_storage_git）になります。

権限

操作 KATATAN のロール GitHub の権限
リポジトリの閲覧、ブランチの切り替え プロジェクトの Viewer 以上 読み取り
CSV の編集・commit、作業ブランチ・PR の作成、新しいテスト仕様書 プロジェクトの Editor 以上 書き込み
テストの開始（レポートの作成） プロジェクトの Editor 以上 読み取り
レポートの閲覧・結果の入力・共有 これまでどおり 不要
「仕様書が更新されています」の表示 これまでどおり 読み取り（ない人には表示されない）
リポジトリの連携・変更・再連携 プロジェクトの Owner、またはワークスペースの Owner 連携するリポジトリにアクセスできること
  • GitHub の権限が「読み取り」だけの人は、閲覧はできますが編集はできません（「閲覧のみです。編集には、GitHub でこのリポジトリへの書き込み権限が必要です。」と表示されます）。
  • GitHub の権限がないメンバーは、リポジトリの中身を見られません。レポートの閲覧・実施はできます。

困ったとき

リポジトリを連携できない

メッセージ 原因と対処
現在はGitHubのリポジトリのみ連携できます。 GitHub 以外の URL です。GitHub のリポジトリを指定してください
リポジトリのURLを入力してください（例: …） URL の形式が正しくありません
リポジトリが見つかりません。URLを確認してください。 URL が誤っているか、アクセス権がありません
KATATAN GitHub App がこのリポジトリに許可されていません。… GitHub で、App のインストール先にこのリポジトリを追加してください
あなたのGitHubアカウントはこのリポジトリにアクセスできないか、… GitHub でリポジトリへのアクセス権を付与してもらってください
ポップアップがブロックされました。… ブラウザでポップアップを許可してください
連携の有効期限が切れました。もう一度お試しください。 連携に10分以上かかりました。最初からやり直してください

「アクセス権がありません」と表示される

「このリポジトリへのアクセス権がありません（owner/name）」と、連携中の GitHub のログイン名が表示されます。

  • 別の GitHub アカウントを使う場合は「別のアカウントでログインし直す」で切り替えられます。
  • リポジトリが削除された場合や、KATATAN GitHub App がリポジトリから外された場合も、同じ表示になります（GitHub の仕様上、区別できません）。

ブランチが見つからない

開いていたブランチが削除されています。「デフォルトブランチ（〜）に切り替える」で戻ってください。

制限事項

項目 現状
対応する Git サービス GitHub のみ（GitLab などは今後の予定）
管理方法の変更 プロジェクトの作成後は変更不可。DB管理から Git管理への移行は今後の予定
編集できるファイル CSV と TSV のみ（ほかは閲覧のみ）
ファイルの大きさ 1ファイル・1回の commit とも 4MB まで。1つのフォルダのファイル数は 10,000 まで
Git LFS 未対応。LFS で管理しているファイルは表示・編集できない
GitHub 側の変更の反映 自動では反映しない（開き直す・「再読み込み」で反映）
同じファイルの同時編集 先に commit した人が優先。後の人には競合として表示する（行単位の自動マージは今後の予定）
レポートの保存先 KATATAN（Git には保存しない）
取り込める画像 PNG・JPEG、1枚 5MB まで
1つのレポートのケース数 10,000 件まで
前のページ
Project
次のページ
Test spec