QuantEngineByItz/docs/GITEA_VARIABLES_FAILURE_ANALYSIS.md

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.