Git mode

Git mode is a project storage mode that lets you manage test specs in the same GitHub repository as your code. Spec changes can be reviewed in the same branch and the same pull request (PR) as the code. Test execution and result sharing continue to happen in KATATAN.

Differences from DB mode

Item	DB mode	Git mode
Where test specs are stored	KATATAN	CSV files in a GitHub repository
Saving	Auto-save	Save = commit (you enter a commit message)
Reviewing changes	KATATAN change history	GitHub PRs
Where test reports are stored	KATATAN	KATATAN (not stored in Git)
MCP tools / CLI commands for specs and test cases	Available	Not available (edit the CSV in the repository directly)

When to use Git mode

• You want to review a new feature and its test spec in the same branch and the same PR
• You want to avoid "the code was updated, but the test spec is still out of date"
• You want members who are not familiar with Git (QA, PMs, etc.) to edit specs using only a browser

Terminology

Term	Meaning
Repository	A place on GitHub where files are stored
Branch	A line of work (series of versions) within a repository, e.g. main, develop
Commit	Saving a set of changes as a single unit. "Saving" in Git mode
PR (pull request)	A request to merge changes from one branch into another. Reviewed on GitHub
Protected branch	A branch where direct changes are prohibited on GitHub. Opened as read-only in KATATAN
Working branch	A personal branch created with Start editing in KATATAN. Named katatan/spec/<username>/<name>
KATATAN-format CSV	A CSV with the columns No, Labels, Test Subject, Preconditions, Steps, Expected Result, Notes, Images. Compatible with KATATAN's CSV export
Snapshot	A copy of the spec contents at the time a report was created. The report does not change even if the spec changes later

Creating a Git-mode project

1. In the project creation dialog, select Git under Test spec storage mode.
2. Enter the GitHub repository URL in Repository URL (e.g. https://github.com/owner/repo).
3. Click Connect repository. A GitHub popup opens; install and authorize the KATATAN GitHub App.
   • If the KATATAN screen does not return after you save on GitHub, click Continue.
4. When a message confirms that the repository is connected (along with its default branch), create the project.

The storage mode cannot be changed after the project is created.

Changing or reconnecting the repository

You can change or reconnect the linked repository from Repository in the project settings (project Owners and workspace Owners only). Existing test reports are kept even if you change the repository.

Signing in to GitHub

Repository content is viewed and edited with each user's own GitHub account permissions. Every member therefore needs to sign in to GitHub once. The first time you open the repository, you are prompted to sign in to GitHub to view it.

• Users who signed in to KATATAN with GitHub still need to authorize GitHub separately. Signing in to KATATAN and granting access to the repository are separate authorizations on GitHub.
• In your account settings (profile), GitHub connection lets you check the connected GitHub login, connect, or disconnect.
• The authorization is refreshed automatically (every 8 hours). You need to sign in again if it goes unused for 6 months or if you revoke it on GitHub.
• Access controls configured on GitHub (team permissions, removal from an organization, SAML SSO, etc.) apply in KATATAN as is. KATATAN servers never clone your entire repository.

Browsing the repository

The sidebar shows the project's repository name (linked to GitHub), a branch switcher, and the files and folders at the root. Below that, under the KATATAN reports heading, Test reports opens the list of reports.

Selecting a file displays it in the main area as follows:

File	Display
Folder	List of contents. README.md is shown below, if present
CSV / TSV	Opened in the table editor (CSV4TEST)
Markdown	Rendered
Image (png / jpg / gif / webp / svg)	Shown as an image
Text / code	Shown as is (only the first 1 MB for files larger than 1 MB)
Other	A "This file cannot be previewed" message with Download and Open on GitHub

• Switching branches: The selected branch is per user (it does not affect what others see). Sharing the URL opens the same branch. Your own working branches are grouped under "My working branches".
• Reload: Changes on GitHub (such as pushes by others) are not reflected automatically. Reopen the file or click Reload to get the latest content.
• If the branch you had open was deleted (e.g. automatically after a PR merge), a message tells you the branch could not be found and may have been deleted by a PR merge. Click Switch to the default branch to go back.

Editing test specs

Only CSV and TSV files can be edited in KATATAN (other files are read-only).

Saving and committing

Clicking the save button (or pressing Ctrl+S) opens a dialog for the commit message; confirming it creates one commit.

• The commit author is the KATATAN user's name and email address.
• When you add images (Images column), they are committed together into the <CSV name>.assets/ folder.
• Unsaved changes are kept in the browser as a draft (they are not lost when you close the tab). A confirmation appears when you try to leave the page.

Start editing and create a PR

• The default branch and protected branches open as read-only. Click Start editing to create your own working branch and edit there.
• From a working branch, Create PR opens a PR targeting the original branch. The PR status (open, merged, closed) is also displayed.
• You can commit directly to unprotected branches.

New test spec

New test spec on a folder screen creates a CSV that contains only the KATATAN-format header row.

When a conflict occurs

If someone else committed to the same file first, KATATAN tells you so, and you can review the contents and save again. Changes to different files are stacked automatically.

Running tests

1. Open a CSV and click Start test with this file in the header (shown to project Editors and above who have read access on GitHub).
2. In the dialog, enter a report name, optionally select a webhook to call on completion, and click Start test.

KATATAN imports the latest contents of the selected branch and creates a test report. Nothing is committed to the repository.

• Created reports can be opened from Test reports in the sidebar (even without signing in to GitHub).
• Recording results, auto-completion, pause / resume / force-complete, share links, CSV export, and webhooks work the same as in DB-mode reports (see Test report).
• The report details show the Source (file, branch, commit). Clicking the file name opens that file in the repository.

When the spec is updated

If the spec is updated after the report was created, the report shows "The spec has been updated since this report was created", and View diff on GitHub lets you review the changes.

• If the source file was moved or deleted, the report shows that the source file cannot be found; if the branch was deleted, it shows that the source branch cannot be found.
• This check uses the viewer's GitHub read permission. It is not shown to users who are not signed in to GitHub.
• The report contents (the snapshot of the imported spec) do not change even when the spec is updated.

CSVs and images that cannot be imported

• CSVs that are not in KATATAN format, have a non-numeric or duplicate No, or contain no test cases are rejected with a reason, and no report is created.
• PNG and JPEG images (Images column) are imported. Images that are missing, in another format, or larger than 5 MB are skipped, and the number of skipped images is displayed (the report itself is still created).

Using the CLI

From @katatan/cli 0.2.0 onward, you can create test reports from local CSV files (see KATATAN CLI for command details).

Copy# Create a test report from a local CSV
katatan report create --spec ./specs/login.csv --name "Regression test 2026-10"

# Export a report to CSV (export only; not synced with KATATAN)
katatan report export <report-id> --out ./report.csv

• report create sends the CSV contents and Git information (current commit, branch, path within the repository, and whether there are uncommitted changes).
  • A warning is shown if there are uncommitted changes. The report is labeled as containing uncommitted changes.
  • In a detached HEAD state (no branch checked out), specify the branch name with --branch.
  • PNG and JPEG images in the <CSV name>.assets/ folder are sent, up to 3 MB in total.
• Existing MCP access tokens cannot be used. Edit the token in MCP Access Control in the project settings and allow create_git_report and export_test_report.
• Report IDs in Git mode have the form {projectId}.git.{reportId} (Copy ID in the UI copies this form).
• In Git-mode projects, MCP tools and CLI commands that operate on specs and test cases return an error (spec_storage_git).

Permissions

Action	KATATAN role	GitHub permission
Browse the repository, switch branches	Project Viewer or above	Read
Edit and commit CSVs, create working branches and PRs, create new test specs	Project Editor or above	Write
Start a test (create a report)	Project Editor or above	Read
View reports, record results, share	Unchanged	Not required
"Spec has been updated" notice	Unchanged	Read (not shown to users without it)
Connect, change, or reconnect the repository	Project Owner or workspace Owner	Access to the repository being connected

• Users with only read permission on GitHub can view but not edit (a message explains that write permission on the repository is required to edit).
• Members without GitHub permission cannot see the repository contents. They can still view and run reports.

Troubleshooting

The repository cannot be connected

Message	Cause and solution
Only GitHub repositories can be connected	The URL is not a GitHub URL. Specify a GitHub repository
Enter a repository URL	The URL format is invalid
Repository not found	The URL is wrong, or you do not have access
The KATATAN GitHub App is not allowed for this repository	On GitHub, add this repository to the App's installation
Your GitHub account cannot access this repository	Ask to be granted access to the repository on GitHub
Popup blocked	Allow popups in your browser
The connection has expired	The connection took more than 10 minutes. Start over

"No access to this repository" is shown

KATATAN shows that you do not have access to the repository (owner/name), along with your connected GitHub login.

• To use a different GitHub account, click Sign in with a different account.
• The same message is shown if the repository has been deleted or the KATATAN GitHub App has been removed from it (GitHub does not allow these cases to be distinguished).

The branch cannot be found

The branch you had open has been deleted. Click Switch to the default branch to go back.

Limitations

Item	Current status
Supported Git services	GitHub only (GitLab and others are planned)
Changing the storage mode	Not possible after project creation. Migration from DB mode to Git mode is planned
Editable files	CSV and TSV only (others are read-only)
File size	Up to 4 MB per file and per commit. Up to 10,000 files per folder
Git LFS	Not supported. Files managed with LFS cannot be viewed or edited
Reflecting changes made on GitHub	Not automatic (reopen the file or click Reload)
Concurrent edits to the same file	The first commit wins; later editors see a conflict (line-level auto-merge is planned)
Where reports are stored	KATATAN (not stored in Git)
Importable images	PNG and JPEG, up to 5 MB each
Test cases per report	Up to 10,000