GitHub Actions — Guardrails and Fix Patterns

Use this when your automation runs in GitHub Actions and you see race conditions, duplicate runs, stale artifacts, secret mismatch, or retrieval steps that look fine but answers drift.

Acceptance targets

ΔS(question, retrieved) ≤ 0.45
coverage ≥ 0.70 to the intended section or record
λ stays convergent across 3 paraphrases

Typical breakpoints → exact fixes

Workflow jobs start before embeddings or the index are ready
Fix No.14: Bootstrap Ordering →
Bootstrap Ordering
First run after deploy uses wrong secret or old model version
Fix No.16: Pre-Deploy Collapse →
Pre-Deploy Collapse
Circular waits between indexing and retrieval jobs or external runners
Fix No.15: Deployment Deadlock →
Deployment Deadlock
High vector similarity but wrong meaning in answers
Fix No.5: Embedding ≠ Semantic →
Embedding ≠ Semantic
Logs cannot explain “why this snippet” was chosen
Fix No.8: Retrieval Traceability →
Retrieval Traceability
Standardize with Data Contracts →
Data Contracts
Hybrid retrieval underperforms single retriever when mixing sources or rerankers
Pattern: Query Parsing Split →
Query Parsing Split
Review Rerankers →
Rerankers
Facts exist in the store but are never retrieved
Pattern: Vectorstore Fragmentation →
Vectorstore Fragmentation

Minimal GitHub Actions workflow with WFGY gates

name: rag-pipeline

on:
  workflow_dispatch:
  push:
    paths:
      - "rag/**"
      - ".github/workflows/rag-pipeline.yml"

env:
  VECTOR_READY_FLAG: vector_ready.txt
  INDEX_HASH_FILE: index_hash.txt
  SECRET_REV: ${{ secrets.SECRET_REV }}

jobs:
  build-index:
    runs-on: ubuntu-latest
    outputs:
      index_hash: ${{ steps.hash.outputs.index_hash }}
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install deps
        run: |
          pip install -r rag/requirements.txt

      - name: Build index
        run: |
          python rag/build_index.py --out artifacts/index.faiss --metric cosine
          echo "ok" > $VECTOR_READY_FLAG

      - name: Compute INDEX_HASH
        id: hash
        run: |
          python - << 'PY'
import hashlib, sys
with open("artifacts/index.faiss","rb") as f:
    h = hashlib.sha256(f.read()).hexdigest()
open("${{ env.INDEX_HASH_FILE }}","w").write(h)
print(f"index_hash={h}")
PY
          echo "index_hash=$(cat $INDEX_HASH_FILE)" >> $GITHUB_OUTPUT

      - name: Upload index artifacts
        uses: actions/upload-artifact@v4
        with:
          name: rag-index
          path: |
            artifacts/index.faiss
            ${{ env.VECTOR_READY_FLAG }}
            ${{ env.INDEX_HASH_FILE }}

  run-llm:
    runs-on: ubuntu-latest
    needs: build-index
    steps:
      - uses: actions/checkout@v4

      - name: Download index artifacts
        uses: actions/download-artifact@v4
        with:
          name: rag-index
          path: artifacts

      - name: Warm-up fence
        run: |
          test -f artifacts/${{ env.VECTOR_READY_FLAG }} || { echo "Vector not ready"; exit 1; }
          test -f artifacts/${{ env.INDEX_HASH_FILE }} || { echo "Missing INDEX_HASH"; exit 1; }
          echo "wf_rev=${{ github.run_id }}"
          echo "secret_rev=${{ env.SECRET_REV }}"
          echo "index_hash=$(cat artifacts/${{ env.INDEX_HASH_FILE }})"

      - name: Run guarded RAG
        env:
          WF_REV: ${{ github.run_id }}
          SECRET_REV: ${{ env.SECRET_REV }}
          INDEX_HASH: ${{ needs.build-index.outputs.index_hash }}
        run: |
          python rag/run_guarded.py \
            --wf-rev "$WF_REV" \
            --secret-rev "$SECRET_REV" \
            --index-hash "$INDEX_HASH" \
            --trace out/trace.json \
            --emit out/answer.json

      - name: ΔS and λ checks
        run: |
          python rag/check_metrics.py --trace out/trace.json --fail-threshold 0.60

      - name: Upload outputs
        uses: actions/upload-artifact@v4
        with:
          name: rag-output
          path: out/

What this enforces

Build and retrieval use the same metric and a single INDEX_HASH.
LLM job hard-fails if the vector layer is not ready.
A separate metrics step rejects runs with ΔS ≥ 0.60 or divergent λ.
Artifacts give you traceability for “why this snippet”.

Specs and recipes RAG Architecture & Recovery · Retrieval Playbook · Retrieval Traceability · Data Contracts

Common GitHub Actions gotchas

Workflow re-runs mutate state Compute a server-side dedupe_key = sha256(run_id + wf_rev + index_hash). Reject duplicates.
Matrix jobs double write to the same index or store Serialize writes or gate on a single producer job. Use needs: fan-in.
Secrets rotate during a long build Stamp secret_rev into artifacts and validate in the consumer job. Abort on mismatch. See Pre-Deploy Collapse
Artifact retention truncates traces that you need for audits Set longer retention or sync traces to durable storage with rev-stamped paths.
Cosine vs inner product mismatch between write and read codepaths Rebuild with explicit metric and normalization. See Embedding ≠ Semantic

When to escalate

ΔS stays ≥ 0.60 after chunk and retrieval fixes Work through the playbook to rebuild and verify. Retrieval Playbook
Same inputs flip answers between runs or branches Check version skew and session state. Pre-Deploy Collapse

🔗 Quick-Start Downloads (60 sec)

Tool	Link	3-Step Setup
WFGY 1.0 PDF	Engine Paper	1️⃣ Download · 2️⃣ Upload to your LLM · 3️⃣ Ask “Answer using WFGY + <your question>”
TXT OS (plain-text OS)	TXTOS.txt	1️⃣ Download · 2️⃣ Paste into any LLM chat · 3️⃣ Type “hello world” — OS boots instantly

🧭 Explore More

Module	Description	Link
WFGY Core	WFGY 2.0 engine is live: full symbolic reasoning architecture and math stack	View →
Problem Map 1.0	Initial 16-mode diagnostic and symbolic fix framework	View →
Problem Map 2.0	RAG-focused failure tree, modular fixes, and pipelines	View →
Semantic Clinic Index	Expanded failure catalog: prompt injection, memory bugs, logic drift	View →
Semantic Blueprint	Layer-based symbolic reasoning & semantic modulations	View →
Benchmark vs GPT-5	Stress test GPT-5 with full WFGY reasoning suite	View →
🧙‍♂️ Starter Village 🏡	New here? Lost in symbols? Click here and let the wizard guide you through	Start →

👑 Early Stargazers: See the Hall of Fame — ⭐ WFGY Engine 2.0 is already unlocked. ⭐ Star the repo to help others discover it and unlock more on the Unlock Board.

11 KiB Raw Blame History Unescape Escape