Fix Gitea seed recovery and workflow guards
This commit is contained in:
@@ -0,0 +1,70 @@
|
||||
# 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.
|
||||
- `outputs/kis_data_collection/kis_data_collection.db` exists.
|
||||
@@ -0,0 +1,58 @@
|
||||
# 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.
|
||||
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.
|
||||
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.
|
||||
Reference in New Issue
Block a user