# 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:

```bash
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.