This runbook explains how to build, validate, and optionally publish the active HK snapshot artifact pack when an operator has prepared a real factor snapshot CSV, or when the workflow generates one from public yfinance data or LongBridge OpenAPI. The resulting reports are background evidence for artifact or content health, not AiGateway online service health, and they are not sufficient by themselves to approve live trading or automatic publish decisions.
The workflow does not approve live trading, deploy Cloud Run, or place broker orders. It only turns a real CSV or generated runtime input into a validated artifact pack and, when explicitly requested, uploads the pack to GCS.
Current supported profile:
hk_low_vol_dividend_quality_snapshot
The workflow is manual-only. There is no schedule until a production HK data-source refresh is implemented and audited.
HK Snapshot Artifact Health runs on weekdays and can also be dispatched manually. It uses the repository's workload identity only to read the currently configured staged snapshot and manifest, then verifies the profile/contract/source identity, SHA-256 digest, and snapshot_as_of freshness. The 40-day budget follows the monthly snapshot-review cadence.
This is not a publisher: it does not generate source data, upload or delete GCS objects, deploy a runtime, change a strategy lifecycle, or submit an order. A failed check creates/updates a parked-evidence issue; refreshes must still come from a reviewed Publish HK Snapshot Artifacts run.
For a local read-only check after gcloud auth application-default login or an equivalent workload identity setup:
hkeq-check-published-snapshot-health \
--profile hk_low_vol_dividend_quality_snapshot \
--snapshot-uri gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_staging/hk_low_vol_dividend_quality_snapshot_factor_snapshot_latest.csv \
--manifest-uri gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_staging/hk_low_vol_dividend_quality_snapshot_factor_snapshot_latest.csv.manifest.json \
--max-age-days 40Use ../examples/low_vol_dividend_quality/production_factor_snapshot.template.csv as the header template.
Required columns:
symbol, sector, close_hkd, adv20_hkd, market_cap_hkd,
dividend_yield_net, dividend_stability_3y, earnings_positive, payout_ratio,
realized_vol_126, beta_252, maxdd_252, mom_6m, mom_12_1,
sma200_gap, suspension_days_63
Recommended columns:
as_of, snapshot_date, eligible, lot_size, pe_ratio,
free_cash_flow_yield, realized_vol_252, corporate_action_flag
Final live order approval still requires more than a valid CSV:
- at least 20 real rows, not sample/smoke rows;
- point-in-time source lineage for prices, fundamentals, dividends, corporate actions, suspensions, and symbol mapping;
- walk-forward out-of-sample backtest evidence;
- broker dry-run order preview, quote, fee, bilingual notification, rollout, and operator approval evidence.
If no real factor snapshot CSV exists yet, prefer input_source_mode=public_yfinance_staging. It generates a public-data runtime input CSV without requiring LongBridge historical market-data permission:
gh workflow run publish-hk-snapshot-artifacts.yml \
--repo QuantStrategyLab/HkEquitySnapshotPipelines \
-f profile=hk_low_vol_dividend_quality_snapshot \
-f input_source_mode=public_yfinance_staging \
-f gcs_prefix=gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_staging \
-f execute_publish=falseThe default universe is ../examples/low_vol_dividend_quality/longbridge_universe.seed.csv. You may override it with universe_path=gs://.../universe.csv. Public yfinance mode stores source_name=public_yfinance_staging and source_quality=public_yfinance_generated when allow_research_defaults=false.
LongBridge OpenAPI mode remains available when the account has the required HK historical market-data entitlement:
gh workflow run publish-hk-snapshot-artifacts.yml \
--repo QuantStrategyLab/HkEquitySnapshotPipelines \
-f profile=hk_low_vol_dividend_quality_snapshot \
-f input_source_mode=longbridge_openapi_staging \
-f gcs_prefix=gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_staging \
-f execute_publish=falseLongBridge mode reads these Google Secret Manager secrets by default, matching the HK LongBridgePlatform naming convention:
longport-app-key-hklongport-app-secret-hklongport_token_hk
The default longbridge_credentials_mode=secret_manager reads these secrets from the longbridgequant GCP project and uses the same Workload Identity Federation naming convention as LongBridgePlatform. If your secret project or secret names differ, override these workflow inputs:
longbridge_secret_project_idlongbridge_app_key_secret_namelongbridge_app_secret_secret_namelongbridge_access_token_secret_name
If the GCP Workload Identity binding is not ready yet, set longbridge_credentials_mode=github_secrets and provide these GitHub Actions secrets instead:
LONGBRIDGE_APP_KEY_HK(alias supported:LONG_BRIDGE_APP_KEY_HK)LONGBRIDGE_APP_SECRET_HK(alias supported:LONG_BRIDGE_APP_SECRET_HK)LONGBRIDGE_ACCESS_TOKEN_HK(aliases supported:LONG_BRIDGE_ACCESS_TOKEN_HK,LONGPORT_ACCESS_TOKEN_HK)
In github_secrets mode, LongBridge input generation does not require GCP auth unless universe_path / factor_snapshot_path uses gs:// or execute_publish=true uploads to GCS.
GitHub-hosted LongBridge credentials are scoped to the single factor-snapshot generation step and are only populated when both input_source_mode=longbridge_openapi_staging and longbridge_credentials_mode=github_secrets. Checkout, dependency installation, public-data generation, artifact validation, upload, and summary steps do not receive those broker credentials. Secret Manager remains the preferred mode.
Important: generated CSVs with allow_research_defaults=false can be runtime artifact inputs after artifact validation and stable GCS publishing, similar to the US snapshot publish flow. They are not final live order approval by themselves; that still requires backtest, broker dry-run, notification, rollout, and operator approval evidence. allow_research_defaults=true remains research smoke only.
For input_source_mode=longbridge_openapi_staging, or any run that reads gs:// inputs or publishes to GCS, the workflow needs a Google Cloud Workload Identity Provider and service account that explicitly allow this repository: QuantStrategyLab/HkEquitySnapshotPipelines. Reusing a provider that is restricted to LongBridgePlatform or UsEquitySnapshotPipelines will fail at the auth step with unauthorized_client / attribute condition. Public yfinance mode without gs:// inputs and without execute_publish=true does not need GCP auth.
Set these repository variables after the GCP binding is created:
GCP_PROJECT_ID: project used by the publish/auth workflow.GCP_WORKLOAD_IDENTITY_PROVIDER: provider whose attribute condition allowsQuantStrategyLab/HkEquitySnapshotPipelines.GCP_WORKLOAD_IDENTITY_SERVICE_ACCOUNT: service account allowed to impersonate through that provider.
The service account needs:
- Secret Manager access to the LongBridge HK secrets in
longbridge_secret_project_id(longport-app-key-hk,longport-app-secret-hk,longport_token_hkby default). - GCS write access to
gcs_prefixonly whenexecute_publish=true.
A workflow smoke test with input_source_mode=factor_snapshot_csv, a repository-local sample CSV, and no gcs_prefix does not require GCP auth. It proves workflow packaging only; it is not runtime artifact evidence.
Open Actions → Publish HK Snapshot Artifacts → Run workflow and set:
profile=hk_low_vol_dividend_quality_snapshot
factor_snapshot_path=gs://<bucket>/hk_equity/inputs/hk_low_vol_dividend_quality_snapshot/factor_snapshot_YYYYMMDD.csv
gcs_prefix=gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_staging
execute_publish=false
Keep execute_publish=false for the first run. The workflow will build the pack, validate it, print the GCS copy plan, and upload the generated files as a GitHub Actions artifact.
After reviewing the generated files, re-run with execute_publish=true to upload to GCS. The publish plan includes:
hk_low_vol_dividend_quality_snapshot_factor_snapshot_latest.csvhk_low_vol_dividend_quality_snapshot_factor_snapshot_latest.csv.manifest.jsonhk_low_vol_dividend_quality_snapshot_ranking_latest.csvrelease_status_summary.jsonartifact_pack_validation.json- optional
source_input_summary.jsonwhen the workflow generated the input from public yfinance or LongBridge OpenAPI
Resolve a remote CSV into a local file:
python scripts/resolve_hk_snapshot_inputs.py \
--factor-snapshot gs://<bucket>/hk_equity/inputs/hk_low_vol_dividend_quality_snapshot/factor_snapshot_YYYYMMDD.csv \
--output-dir data/input/resolved/hk_low_vol_dividend_quality_snapshot \
--env-output /tmp/resolved_hk_snapshot_inputs.env
source /tmp/resolved_hk_snapshot_inputs.envBuild and validate:
hkeq-build-low-vol-dividend-quality-snapshot \
--factor-snapshot "$FACTOR_SNAPSHOT_PATH" \
--output-dir data/output/low_vol_dividend_quality \
--min-adv20-hkd 5000000 \
--min-market-cap-hkd 2000000000
hkeq-validate-snapshot-artifact-pack \
--profile hk_low_vol_dividend_quality_snapshot \
--artifact-dir data/output/low_vol_dividend_quality \
--json > data/output/low_vol_dividend_quality/artifact_pack_validation.jsonPrint the GCS publish plan:
python scripts/publish_hk_snapshot_artifacts.py \
--profile hk_low_vol_dividend_quality_snapshot \
--artifact-dir data/output/low_vol_dividend_quality \
--gcs-prefix gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_stagingUpload only after review:
python scripts/publish_hk_snapshot_artifacts.py \
--profile hk_low_vol_dividend_quality_snapshot \
--artifact-dir data/output/low_vol_dividend_quality \
--gcs-prefix gs://<bucket>/strategy-artifacts/hk_equity/hk_low_vol_dividend_quality_snapshot_staging \
--execute- Do not use
examples/*/factor_snapshot.sample.csvas production evidence. - Do not pass signed URLs or URLs containing
token=,password=,signature=, or similar secret-like query parameters. - Use a staging GCS prefix first; only promote to a production prefix after runtime artifact evidence, source lineage, backtest, and operator approval evidence are reviewed.
- This workflow does not remove dry-run controls from LongBridge or IBKR.