# Gitea Variables Failure Analysis Guide

Use this when a Gitea Actions run fails after the `vars` migration.

## Decision tree

### 1. Workflow never starts

Likely causes:

- workflow file not committed
- runner offline
- dispatch permission issue

Empirical note:

- A direct API dispatch probe to the workflow endpoint returned `401 Unauthorized` in this workspace, which means API-triggered execution still needs a valid repository token.
- With `GITEA_TOKEN_HOME`, dispatch succeeds and creates a queued run, so the remaining bottleneck can be runner capacity rather than API auth.

Observed root cause for `run 161`:

- `Checkout Code` failed because the checked-out commit did not contain `GatherTradingData.json`.
- The job log shows `::error::GatherTradingData.json 없음 — canonical seed snapshot이 필요합니다.`
- `git ls-tree --name-only -r HEAD -- GatherTradingData.json` in this workspace returned no tracked file, so the file exists locally but is not part of the repository tree used by the runner.

Current workflow correction:

- A dedicated `Prepare Raw Seed Snapshot` step now checks for `GatherTradingData.json` first.
- If JSON is missing but `GatherTradingData.xlsx` exists, the workflow regenerates JSON with `tools/convert_xlsx_to_json.py`.
- If both are missing and `.clasprc.json` is present, the workflow attempts to download `GatherTradingData.xlsx` from Google Drive and then regenerate JSON.
- If both are missing and no download credential is available, the workflow emits explicit recovery instructions instead of failing with a generic checkout error.

### 2. Step fails with `missing or empty`

Likely causes:

- repo variable not created
- variable name typo
- variable value is blank

### 3. Python fails with `environment variables not found`

Likely causes:

- workflow maps the wrong name into the env block
- repo variable scope is wrong
- runner executed an older checkout

### 4. Collector starts but no DB/report is written

Likely causes:

- `GatherTradingData.json` missing
- `.clasprc.json` missing or Google Drive export denied
- KIS connectivity/auth issue
- target path permissions on the runner

## What to inspect first

1. The exact failing step name.
2. The first shell error line.
3. Whether the workflow job log shows `vars.KIS_APP_*` in the YAML revision used by the run.
4. Whether the output files were created before failure.

## Expected healthy signature

- Credential validation step passes.
- Collector step passes.
- `Temp/kis_data_collection_v1.json` exists.
- `src/quant_engine/kis_data_collection.db` exists.