GitHub Actions — Guardrails and Fix Patterns

🧭 Quick Return to Map

You are in a sub-page of Automation Platforms.
To reorient, go back here:

Automation Platforms — stabilize no-code workflows and integrations

WFGY Global Fix Map — main Emergency Room, 300+ structured fixes

WFGY Problem Map 1.0 — 16 reproducible failure modes

Think of this page as a desk within a ward.
If you need the full triage and all prescriptions, return to the Emergency Room lobby.

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

Layer	Page	What it’s for
Proof	WFGY Recognition Map	External citations, integrations, and ecosystem proof
Engine	WFGY 1.0	Original PDF based tension engine
Engine	WFGY 2.0	Production tension kernel and math engine for RAG and agents
Engine	WFGY 3.0	TXT based Singularity tension engine, 131 S class set
Map	Problem Map 1.0	Flagship 16 problem RAG failure checklist and fix map
Map	Problem Map 2.0	RAG focused recovery pipeline
Map	Problem Map 3.0	Global Debug Card, image as a debug protocol layer
Map	Semantic Clinic	Symptom to family to exact fix
Map	Grandma’s Clinic	Plain language stories mapped to Problem Map 1.0
Onboarding	Starter Village	Guided tour for newcomers
App	TXT OS	TXT semantic OS, fast boot
App	Blah Blah Blah	Abstract and paradox Q and A built on TXT OS
App	Blur Blur Blur	Text to image with semantic control
App	Blow Blow Blow	Reasoning game engine and memory demo

If this repository helped, starring it improves discovery so more builders can find the docs and tools.

10 KiB Raw Blame History Unescape Escape