QuantEngineByItz/docs/GITEA_VARIABLES_RUNBOOK.md

Gitea Variables Runbook

Short operator flow for KIS variable-backed workflows.

Before you run

• Confirm these repo variables exist:
  • KIS_APP_KEY_TEST
  • KIS_APP_SECRET_TEST
  • KIS_APP_KEY
  • KIS_APP_SECRET
• Confirm the workflows reference vars.KIS_APP_*, not secrets.KIS_APP_*.
• Confirm the seed snapshot is available as either:
  • GatherTradingData.json, or
  • GatherTradingData.xlsx for runtime regeneration.
• If both are missing, the workflow can optionally fetch GatherTradingData.xlsx from Google Drive when .clasprc.json is present in the runner workspace.

Run order

1. Trigger .gitea/workflows/kis_data_collection.yml with workflow_dispatch.
2. Confirm the mock credential step passes in --dry-run mode.
3. Confirm the real collection step writes:
   • Temp/kis_data_collection_v1.json
   • outputs/kis_data_collection/kis_data_collection.db
4. Trigger .gitea/workflows/qualitative_sell_strategy.yml.
5. Confirm the mock credential step passes in --dry-run mode.
6. Confirm the batch build step sees KIS_APP_KEY and KIS_APP_SECRET.

If it fails

• If an API dispatch probe returns 401 Unauthorized, the session does not have a repository write token and cannot trigger the workflow by API.
• If the job stops on missing or empty, the variable name exists in workflow text but the repo variable is missing or blank.
• If the job stops before Python starts, the runner may be using an old workflow revision.
• If Python raises environment variables not found, the repo variable exists but is not injected into the job environment.
• If the collector writes no SQLite output, check GatherTradingData.json presence and KIS API connectivity.
• If the job fails at Prepare Raw Seed Snapshot, provision the missing seed file in the repository tree or add a download step before collection.
• If the job fails while downloading GatherTradingData.xlsx, check Google Drive access, .clasprc.json, and the spreadsheet export permission for the service account / refresh token.

What to attach when asking for help

• Job URL
• Failing step name
• First error line
• Whether the failure is in:
  • variable resolution
  • Python credential loading
  • API connectivity
  • SQLite write

API-trigger path

If you have GITEA_TOKEN_HOME available, you can use the token harness:

python tools/validate_gitea_token_home_v1.py --dispatch --workflow kis_data_collection.yml --ref main

The token harness documents the direct API path and can be used when UI dispatch is not convenient.