# GITEA_TOKEN_HOME Runbook

## 1. Confirm presence

Check that `GITEA_TOKEN_HOME` is set in the shell that runs the harness.

## 2. Validate read-only access

```bash
python tools/validate_gitea_token_home_v1.py
```

Expected:

- `gate = PASS`
- repo access works
- workflow metadata is readable

## 3. Dispatch smoke test

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

Expected:

- dispatch returns `204` or `201`
- latest run is visible in the API
- run status becomes visible in the response payload

## 4. If it fails

- `GITEA_TOKEN_HOME missing or empty`: environment is not configured
- `401 Unauthorized`: token is wrong or lacks repo scope
- `404 Not Found`: repo or workflow path mismatch
- `latest_run_missing`: dispatch accepted, but run listing lagged behind
- `queued` or long `in_progress`: runner is busy or the job is waiting for the self-hosted runner slot

## 5. Evidence to capture

- Harness JSON output
- Workflow run URL
- Failing step name if the dispatched run fails
- Runner status from the API if the job stays queued

## Current run 161 finding

- `Checkout Code` failed before Python started.
- The repository checkout did not contain `GatherTradingData.json`.
- This means the next fix is not token-related; it is seed-file availability at workflow runtime.
- The workflow is now updated to regenerate the JSON from `GatherTradingData.xlsx` when possible and to fail with explicit recovery instructions when both are missing.