From 8c5a62a7f6d1ccb5c09c8ff954e7284e4d91aa62 Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Wed, 4 Feb 2026 15:20:33 -0500
Subject: [PATCH 1/7] feat: add GitHub Action to trigger docs ingestion
 workflow

Triggers ingestDocsWorkflow on Mastra when MDX/MD files are pushed to main.
Uses RUNPOD_ASSISTANT_BASE_URL and RUNPOD_ASSISTANT_API_KEY for configuration.
---
 .github/workflows/trigger-docs-ingestion.yml | 53 ++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 .github/workflows/trigger-docs-ingestion.yml

diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
new file mode 100644
index 00000000..0a123ba8
--- /dev/null
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -0,0 +1,53 @@
+name: Trigger Docs Ingestion
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**.mdx'
+      - '**.md'
+      - 'docs.json'
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  trigger-ingestion:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger Mastra Docs Ingestion Workflow
+        env:
+          RUNPOD_ASSISTANT_BASE_URL: ${{ vars.RUNPOD_ASSISTANT_BASE_URL }}
+          RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
+        run: |
+          set -euo pipefail
+
+          RUN_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
+          echo "Run ID: $RUN_ID"
+
+          # Helper function to make API calls and handle responses
+          make_request() {
+            local endpoint="$1"
+            local data="$2"
+            local description="$3"
+
+            echo "$description..."
+            response=$(curl -s -w "\n%{http_code}" --max-time 30 -X POST \
+              "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/ingestDocsWorkflow/${endpoint}?runId=$RUN_ID" \
+              -H "Content-Type: application/json" \
+              -H "Authorization: Bearer ${RUNPOD_ASSISTANT_API_KEY}" \
+              -d "$data")
+
+            http_code=$(echo "$response" | tail -n1)
+            body=$(echo "$response" | sed '$d')
+            echo "Response: $body (HTTP $http_code)"
+
+            if [ "$http_code" -ne 200 ]; then
+              echo "ERROR: $description failed"
+              exit 1
+            fi
+          }
+
+          make_request "create-run" '{}' "Creating workflow run"
+          make_request "start" '{"inputData": {"branch": "main"}}' "Starting workflow run"
+
+          echo "Successfully triggered docs ingestion workflow"

From ced4660acc2e3e876101ad1e1783bac5d21e9cba Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Wed, 4 Feb 2026 15:22:11 -0500
Subject: [PATCH 2/7] feat: add PR validation for auth and workflow existence

Validates on PR open:
- RUNPOD_ASSISTANT_BASE_URL variable is configured
- RUNPOD_ASSISTANT_API_KEY secret is configured
- Authentication works
- ingestDocsWorkflow exists on the target server

Prevents merge failures by catching config issues early.
---
 .github/workflows/trigger-docs-ingestion.yml | 70 +++++++++++++++++++-
 1 file changed, 69 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
index 0a123ba8..a311e064 100644
--- a/.github/workflows/trigger-docs-ingestion.yml
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -8,10 +8,79 @@ on:
       - '**.mdx'
       - '**.md'
       - 'docs.json'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - '**.mdx'
+      - '**.md'
+      - 'docs.json'
   workflow_dispatch: # Allow manual trigger
 
 jobs:
+  # Validates configuration on PRs - ensures auth works before merge
+  validate-config:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate Ingestion Workflow Configuration
+        env:
+          RUNPOD_ASSISTANT_BASE_URL: ${{ vars.RUNPOD_ASSISTANT_BASE_URL }}
+          RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
+        run: |
+          set -euo pipefail
+
+          # Check required environment variables are set
+          if [ -z "${RUNPOD_ASSISTANT_BASE_URL:-}" ]; then
+            echo "ERROR: RUNPOD_ASSISTANT_BASE_URL variable is not configured"
+            echo "Go to Settings → Secrets and variables → Actions → Variables"
+            exit 1
+          fi
+          echo "✓ RUNPOD_ASSISTANT_BASE_URL is configured"
+
+          if [ -z "${RUNPOD_ASSISTANT_API_KEY:-}" ]; then
+            echo "ERROR: RUNPOD_ASSISTANT_API_KEY secret is not configured"
+            echo "Go to Settings → Secrets and variables → Actions → Secrets"
+            exit 1
+          fi
+          echo "✓ RUNPOD_ASSISTANT_API_KEY is configured"
+
+          # Validate auth and workflow existence by creating a test run
+          # Note: This creates an unstarted run as a side effect (harmless)
+          RUN_ID="validation-$(uuidgen | tr '[:upper:]' '[:lower:]')"
+          echo "Validating authentication and workflow existence..."
+
+          response=$(curl -s -w "\n%{http_code}" --max-time 30 -X POST \
+            "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/ingestDocsWorkflow/create-run?runId=$RUN_ID" \
+            -H "Content-Type: application/json" \
+            -H "Authorization: Bearer ${RUNPOD_ASSISTANT_API_KEY}" \
+            -d '{}')
+
+          http_code=$(echo "$response" | tail -n1)
+          body=$(echo "$response" | sed '$d')
+
+          if [ "$http_code" -eq 401 ] || [ "$http_code" -eq 403 ]; then
+            echo "ERROR: Authentication failed (HTTP $http_code)"
+            echo "Check that RUNPOD_ASSISTANT_API_KEY is correct"
+            exit 1
+          elif [ "$http_code" -eq 404 ]; then
+            echo "ERROR: Workflow 'ingestDocsWorkflow' not found (HTTP $http_code)"
+            echo "Verify the workflow is deployed to: ${RUNPOD_ASSISTANT_BASE_URL}"
+            exit 1
+          elif [ "$http_code" -ne 200 ]; then
+            echo "ERROR: Unexpected response (HTTP $http_code)"
+            echo "Response: $body"
+            exit 1
+          fi
+
+          echo "✓ Authentication successful"
+          echo "✓ Workflow 'ingestDocsWorkflow' exists"
+          echo ""
+          echo "Configuration validated - safe to merge"
+
+  # Triggers the actual ingestion on merge to main
   trigger-ingestion:
+    if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
       - name: Trigger Mastra Docs Ingestion Workflow
@@ -24,7 +93,6 @@ jobs:
           RUN_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
           echo "Run ID: $RUN_ID"
 
-          # Helper function to make API calls and handle responses
           make_request() {
             local endpoint="$1"
             local data="$2"

From 0c517b3d4483775b9e745d0a63331790b388a32b Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Wed, 4 Feb 2026 15:23:53 -0500
Subject: [PATCH 3/7] refactor: improve error messages with GitHub annotations
 and clear fix instructions

---
 .github/workflows/trigger-docs-ingestion.yml | 125 +++++++++++++++----
 1 file changed, 98 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
index a311e064..fd12a4c2 100644
--- a/.github/workflows/trigger-docs-ingestion.yml
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -32,22 +32,27 @@ jobs:
 
           # Check required environment variables are set
           if [ -z "${RUNPOD_ASSISTANT_BASE_URL:-}" ]; then
-            echo "ERROR: RUNPOD_ASSISTANT_BASE_URL variable is not configured"
-            echo "Go to Settings → Secrets and variables → Actions → Variables"
+            echo "::error::RUNPOD_ASSISTANT_BASE_URL is not configured"
+            echo ""
+            echo "To fix: Go to Settings > Secrets and variables > Actions > Variables"
+            echo "Add a variable named RUNPOD_ASSISTANT_BASE_URL with the Mastra endpoint URL"
             exit 1
           fi
-          echo "✓ RUNPOD_ASSISTANT_BASE_URL is configured"
+          echo "[OK] RUNPOD_ASSISTANT_BASE_URL is configured"
 
           if [ -z "${RUNPOD_ASSISTANT_API_KEY:-}" ]; then
-            echo "ERROR: RUNPOD_ASSISTANT_API_KEY secret is not configured"
-            echo "Go to Settings → Secrets and variables → Actions → Secrets"
+            echo "::error::RUNPOD_ASSISTANT_API_KEY is not configured"
+            echo ""
+            echo "To fix: Go to Settings > Secrets and variables > Actions > Secrets"
+            echo "Add a secret named RUNPOD_ASSISTANT_API_KEY with the API key"
             exit 1
           fi
-          echo "✓ RUNPOD_ASSISTANT_API_KEY is configured"
+          echo "[OK] RUNPOD_ASSISTANT_API_KEY is configured"
 
           # Validate auth and workflow existence by creating a test run
           # Note: This creates an unstarted run as a side effect (harmless)
           RUN_ID="validation-$(uuidgen | tr '[:upper:]' '[:lower:]')"
+          echo ""
           echo "Validating authentication and workflow existence..."
 
           response=$(curl -s -w "\n%{http_code}" --max-time 30 -X POST \
@@ -59,24 +64,46 @@ jobs:
           http_code=$(echo "$response" | tail -n1)
           body=$(echo "$response" | sed '$d')
 
-          if [ "$http_code" -eq 401 ] || [ "$http_code" -eq 403 ]; then
-            echo "ERROR: Authentication failed (HTTP $http_code)"
-            echo "Check that RUNPOD_ASSISTANT_API_KEY is correct"
-            exit 1
-          elif [ "$http_code" -eq 404 ]; then
-            echo "ERROR: Workflow 'ingestDocsWorkflow' not found (HTTP $http_code)"
-            echo "Verify the workflow is deployed to: ${RUNPOD_ASSISTANT_BASE_URL}"
-            exit 1
-          elif [ "$http_code" -ne 200 ]; then
-            echo "ERROR: Unexpected response (HTTP $http_code)"
-            echo "Response: $body"
-            exit 1
+          if [ "$http_code" -eq 200 ]; then
+            echo "[OK] Authentication successful"
+            echo "[OK] Workflow 'ingestDocsWorkflow' exists"
+            echo ""
+            echo "Configuration validated - safe to merge"
+            exit 0
           fi
 
-          echo "✓ Authentication successful"
-          echo "✓ Workflow 'ingestDocsWorkflow' exists"
+          # Provide specific error messages based on HTTP status
+          echo ""
+          echo "Response body: $body"
           echo ""
-          echo "Configuration validated - safe to merge"
+
+          case "$http_code" in
+            401|403)
+              echo "::error::Authentication failed (HTTP $http_code)"
+              echo ""
+              echo "Cause: The API key was rejected by the server"
+              echo "To fix: Verify RUNPOD_ASSISTANT_API_KEY is correct in repository secrets"
+              ;;
+            404)
+              echo "::error::Workflow not found (HTTP $http_code)"
+              echo ""
+              echo "Cause: The workflow 'ingestDocsWorkflow' does not exist at the endpoint"
+              echo "To fix: Verify the workflow is deployed at ${RUNPOD_ASSISTANT_BASE_URL}"
+              ;;
+            500|502|503|504)
+              echo "::error::Server error (HTTP $http_code)"
+              echo ""
+              echo "Cause: The runpod-assistant service returned a server error"
+              echo "To fix: Check if runpod-assistant is healthy at ${RUNPOD_ASSISTANT_BASE_URL}"
+              ;;
+            *)
+              echo "::error::Unexpected error (HTTP $http_code)"
+              echo ""
+              echo "Cause: Unknown - see response body above"
+              ;;
+          esac
+
+          exit 1
 
   # Triggers the actual ingestion on merge to main
   trigger-ingestion:
@@ -90,15 +117,32 @@ jobs:
         run: |
           set -euo pipefail
 
+          # Validate required configuration before attempting requests
+          if [ -z "${RUNPOD_ASSISTANT_BASE_URL:-}" ]; then
+            echo "::error::RUNPOD_ASSISTANT_BASE_URL is not configured"
+            echo ""
+            echo "To fix: Go to Settings > Secrets and variables > Actions > Variables"
+            echo "Add a variable named RUNPOD_ASSISTANT_BASE_URL with the Mastra endpoint URL"
+            exit 1
+          fi
+
+          if [ -z "${RUNPOD_ASSISTANT_API_KEY:-}" ]; then
+            echo "::error::RUNPOD_ASSISTANT_API_KEY is not configured"
+            echo ""
+            echo "To fix: Go to Settings > Secrets and variables > Actions > Secrets"
+            echo "Add a secret named RUNPOD_ASSISTANT_API_KEY with the API key"
+            exit 1
+          fi
+
           RUN_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
           echo "Run ID: $RUN_ID"
 
           make_request() {
             local endpoint="$1"
             local data="$2"
-            local description="$3"
+            local step_name="$3"
 
-            echo "$description..."
+            echo "$step_name..."
             response=$(curl -s -w "\n%{http_code}" --max-time 30 -X POST \
               "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/ingestDocsWorkflow/${endpoint}?runId=$RUN_ID" \
               -H "Content-Type: application/json" \
@@ -107,15 +151,42 @@ jobs:
 
             http_code=$(echo "$response" | tail -n1)
             body=$(echo "$response" | sed '$d')
-            echo "Response: $body (HTTP $http_code)"
 
-            if [ "$http_code" -ne 200 ]; then
-              echo "ERROR: $description failed"
-              exit 1
+            if [ "$http_code" -eq 200 ]; then
+              echo "Success: $body"
+              return 0
             fi
+
+            # Provide specific error messages based on HTTP status
+            echo "::error::$step_name failed with HTTP $http_code"
+            echo ""
+            echo "Response body: $body"
+            echo ""
+
+            case "$http_code" in
+              401|403)
+                echo "Cause: Authentication failed"
+                echo "To fix: Verify RUNPOD_ASSISTANT_API_KEY is correct in repository secrets"
+                ;;
+              404)
+                echo "Cause: Workflow 'ingestDocsWorkflow' not found"
+                echo "To fix: Verify the workflow is deployed at ${RUNPOD_ASSISTANT_BASE_URL}"
+                ;;
+              500|502|503|504)
+                echo "Cause: Server error at ${RUNPOD_ASSISTANT_BASE_URL}"
+                echo "To fix: Check if runpod-assistant is healthy; retry the workflow"
+                ;;
+              *)
+                echo "Cause: Unexpected error"
+                echo "To fix: Check the response body above for details"
+                ;;
+            esac
+
+            exit 1
           }
 
           make_request "create-run" '{}' "Creating workflow run"
           make_request "start" '{"inputData": {"branch": "main"}}' "Starting workflow run"
 
+          echo ""
           echo "Successfully triggered docs ingestion workflow"

From a6c0ed5129c2c280c1c02b8622bd5d680f0453db Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Wed, 4 Feb 2026 15:26:55 -0500
Subject: [PATCH 4/7] feat: trigger validation when workflow file itself
 changes

---
 .github/workflows/trigger-docs-ingestion.yml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
index fd12a4c2..552c6c28 100644
--- a/.github/workflows/trigger-docs-ingestion.yml
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -8,6 +8,7 @@ on:
       - '**.mdx'
       - '**.md'
       - 'docs.json'
+      - '.github/workflows/trigger-docs-ingestion.yml'
   pull_request:
     branches:
       - main
@@ -15,6 +16,7 @@ on:
       - '**.mdx'
       - '**.md'
       - 'docs.json'
+      - '.github/workflows/trigger-docs-ingestion.yml'
   workflow_dispatch: # Allow manual trigger
 
 jobs:

From 902dd35d42300244ace85e4021298741ba217fbd Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Wed, 4 Feb 2026 15:28:56 -0500
Subject: [PATCH 5/7] refactor: extract ingestion logic to standalone script

- Move all bash logic to .github/scripts/trigger-ingestion.sh
- Workflow file is now simple and declarative
- Script is readable, testable locally, and well-documented
- Added VALIDATE_ONLY mode for PR checks
---
 .github/scripts/trigger-ingestion.sh         | 153 +++++++++++++++++
 .github/workflows/trigger-docs-ingestion.yml | 168 ++-----------------
 2 files changed, 165 insertions(+), 156 deletions(-)
 create mode 100755 .github/scripts/trigger-ingestion.sh

diff --git a/.github/scripts/trigger-ingestion.sh b/.github/scripts/trigger-ingestion.sh
new file mode 100755
index 00000000..1ca8ee3d
--- /dev/null
+++ b/.github/scripts/trigger-ingestion.sh
@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+#
+# Triggers the ingestDocsWorkflow on the Runpod Assistant.
+# Used by GitHub Actions to sync documentation changes.
+#
+# Required environment variables:
+#   RUNPOD_ASSISTANT_BASE_URL - Base URL of the assistant API
+#   RUNPOD_ASSISTANT_API_KEY  - API key for authentication
+#
+# Optional:
+#   VALIDATE_ONLY=true - Only validate config, don't trigger ingestion
+#
+
+set -euo pipefail
+
+# --- Configuration ---
+WORKFLOW_ID="ingestDocsWorkflow"
+TIMEOUT_SECONDS=30
+
+# --- Helper Functions ---
+
+log()       { echo "$*"; }
+log_ok()    { echo "[OK] $*"; }
+log_error() { echo "::error::$*"; }
+
+check_required_var() {
+    local var_name="$1"
+    local fix_location="$2"
+
+    if [ -z "${!var_name:-}" ]; then
+        log_error "$var_name is not configured"
+        log ""
+        log "To fix: Go to Settings > Secrets and variables > Actions > $fix_location"
+        log "Add: $var_name"
+        exit 1
+    fi
+    log_ok "$var_name is configured"
+}
+
+# Makes an API request and handles the response
+# Returns: 0 on success, 1 on failure
+api_request() {
+    local endpoint="$1"
+    local data="$2"
+    local description="$3"
+
+    log "$description..."
+
+    # Make request, capture response and status separately
+    local http_status
+    local response
+
+    response=$(curl -s -w "\nHTTP_STATUS:%{http_code}" \
+        --max-time "$TIMEOUT_SECONDS" \
+        -X POST \
+        "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/${WORKFLOW_ID}/${endpoint}" \
+        -H "Content-Type: application/json" \
+        -H "Authorization: Bearer ${RUNPOD_ASSISTANT_API_KEY}" \
+        -d "$data")
+
+    # Extract status code from response
+    http_status=$(echo "$response" | grep "HTTP_STATUS:" | cut -d: -f2)
+    response=$(echo "$response" | grep -v "HTTP_STATUS:")
+
+    # Handle response based on status code
+    case "$http_status" in
+        200)
+            log_ok "$description succeeded"
+            return 0
+            ;;
+        401|403)
+            log_error "$description failed - Authentication error (HTTP $http_status)"
+            log ""
+            log "Response: $response"
+            log ""
+            log "Cause: The API key was rejected"
+            log "To fix: Check RUNPOD_ASSISTANT_API_KEY in repository secrets"
+            return 1
+            ;;
+        404)
+            log_error "$description failed - Workflow not found (HTTP $http_status)"
+            log ""
+            log "Response: $response"
+            log ""
+            log "Cause: Workflow '$WORKFLOW_ID' doesn't exist at this endpoint"
+            log "To fix: Verify workflow is deployed at $RUNPOD_ASSISTANT_BASE_URL"
+            return 1
+            ;;
+        500|502|503|504)
+            log_error "$description failed - Server error (HTTP $http_status)"
+            log ""
+            log "Response: $response"
+            log ""
+            log "Cause: The assistant service returned an error"
+            log "To fix: Check if runpod-assistant is healthy, then retry"
+            return 1
+            ;;
+        *)
+            log_error "$description failed - Unexpected error (HTTP $http_status)"
+            log ""
+            log "Response: $response"
+            return 1
+            ;;
+    esac
+}
+
+# --- Main ---
+
+main() {
+    log "=== Docs Ingestion Workflow ==="
+    log ""
+
+    # Validate required environment variables
+    log "Checking configuration..."
+    check_required_var "RUNPOD_ASSISTANT_BASE_URL" "Variables"
+    check_required_var "RUNPOD_ASSISTANT_API_KEY" "Secrets"
+    log ""
+
+    # Generate unique run ID
+    local run_id
+    run_id=$(uuidgen | tr '[:upper:]' '[:lower:]')
+
+    if [ "${VALIDATE_ONLY:-false}" = "true" ]; then
+        run_id="validation-$run_id"
+    fi
+
+    log "Run ID: $run_id"
+    log ""
+
+    # Step 1: Create workflow run
+    if ! api_request "create-run?runId=$run_id" '{}' "Creating workflow run"; then
+        exit 1
+    fi
+
+    # If validation only, stop here
+    if [ "${VALIDATE_ONLY:-false}" = "true" ]; then
+        log ""
+        log "=== Validation Complete ==="
+        log "Configuration is valid - safe to merge"
+        exit 0
+    fi
+
+    # Step 2: Start workflow run
+    if ! api_request "start?runId=$run_id" '{"inputData": {"branch": "main"}}' "Starting workflow run"; then
+        exit 1
+    fi
+
+    log ""
+    log "=== Success ==="
+    log "Docs ingestion workflow triggered"
+}
+
+main "$@"
diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
index 552c6c28..6ac3eb65 100644
--- a/.github/workflows/trigger-docs-ingestion.yml
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -9,6 +9,7 @@ on:
       - '**.md'
       - 'docs.json'
       - '.github/workflows/trigger-docs-ingestion.yml'
+      - '.github/scripts/trigger-ingestion.sh'
   pull_request:
     branches:
       - main
@@ -17,7 +18,8 @@ on:
       - '**.md'
       - 'docs.json'
       - '.github/workflows/trigger-docs-ingestion.yml'
-  workflow_dispatch: # Allow manual trigger
+      - '.github/scripts/trigger-ingestion.sh'
+  workflow_dispatch:
 
 jobs:
   # Validates configuration on PRs - ensures auth works before merge
@@ -25,170 +27,24 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - name: Validate Ingestion Workflow Configuration
+      - uses: actions/checkout@v4
+
+      - name: Validate configuration
         env:
           RUNPOD_ASSISTANT_BASE_URL: ${{ vars.RUNPOD_ASSISTANT_BASE_URL }}
           RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
-        run: |
-          set -euo pipefail
-
-          # Check required environment variables are set
-          if [ -z "${RUNPOD_ASSISTANT_BASE_URL:-}" ]; then
-            echo "::error::RUNPOD_ASSISTANT_BASE_URL is not configured"
-            echo ""
-            echo "To fix: Go to Settings > Secrets and variables > Actions > Variables"
-            echo "Add a variable named RUNPOD_ASSISTANT_BASE_URL with the Mastra endpoint URL"
-            exit 1
-          fi
-          echo "[OK] RUNPOD_ASSISTANT_BASE_URL is configured"
-
-          if [ -z "${RUNPOD_ASSISTANT_API_KEY:-}" ]; then
-            echo "::error::RUNPOD_ASSISTANT_API_KEY is not configured"
-            echo ""
-            echo "To fix: Go to Settings > Secrets and variables > Actions > Secrets"
-            echo "Add a secret named RUNPOD_ASSISTANT_API_KEY with the API key"
-            exit 1
-          fi
-          echo "[OK] RUNPOD_ASSISTANT_API_KEY is configured"
-
-          # Validate auth and workflow existence by creating a test run
-          # Note: This creates an unstarted run as a side effect (harmless)
-          RUN_ID="validation-$(uuidgen | tr '[:upper:]' '[:lower:]')"
-          echo ""
-          echo "Validating authentication and workflow existence..."
-
-          response=$(curl -s -w "\n%{http_code}" --max-time 30 -X POST \
-            "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/ingestDocsWorkflow/create-run?runId=$RUN_ID" \
-            -H "Content-Type: application/json" \
-            -H "Authorization: Bearer ${RUNPOD_ASSISTANT_API_KEY}" \
-            -d '{}')
-
-          http_code=$(echo "$response" | tail -n1)
-          body=$(echo "$response" | sed '$d')
-
-          if [ "$http_code" -eq 200 ]; then
-            echo "[OK] Authentication successful"
-            echo "[OK] Workflow 'ingestDocsWorkflow' exists"
-            echo ""
-            echo "Configuration validated - safe to merge"
-            exit 0
-          fi
-
-          # Provide specific error messages based on HTTP status
-          echo ""
-          echo "Response body: $body"
-          echo ""
-
-          case "$http_code" in
-            401|403)
-              echo "::error::Authentication failed (HTTP $http_code)"
-              echo ""
-              echo "Cause: The API key was rejected by the server"
-              echo "To fix: Verify RUNPOD_ASSISTANT_API_KEY is correct in repository secrets"
-              ;;
-            404)
-              echo "::error::Workflow not found (HTTP $http_code)"
-              echo ""
-              echo "Cause: The workflow 'ingestDocsWorkflow' does not exist at the endpoint"
-              echo "To fix: Verify the workflow is deployed at ${RUNPOD_ASSISTANT_BASE_URL}"
-              ;;
-            500|502|503|504)
-              echo "::error::Server error (HTTP $http_code)"
-              echo ""
-              echo "Cause: The runpod-assistant service returned a server error"
-              echo "To fix: Check if runpod-assistant is healthy at ${RUNPOD_ASSISTANT_BASE_URL}"
-              ;;
-            *)
-              echo "::error::Unexpected error (HTTP $http_code)"
-              echo ""
-              echo "Cause: Unknown - see response body above"
-              ;;
-          esac
-
-          exit 1
+          VALIDATE_ONLY: "true"
+        run: .github/scripts/trigger-ingestion.sh
 
   # Triggers the actual ingestion on merge to main
   trigger-ingestion:
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     steps:
-      - name: Trigger Mastra Docs Ingestion Workflow
+      - uses: actions/checkout@v4
+
+      - name: Trigger docs ingestion
         env:
           RUNPOD_ASSISTANT_BASE_URL: ${{ vars.RUNPOD_ASSISTANT_BASE_URL }}
           RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
-        run: |
-          set -euo pipefail
-
-          # Validate required configuration before attempting requests
-          if [ -z "${RUNPOD_ASSISTANT_BASE_URL:-}" ]; then
-            echo "::error::RUNPOD_ASSISTANT_BASE_URL is not configured"
-            echo ""
-            echo "To fix: Go to Settings > Secrets and variables > Actions > Variables"
-            echo "Add a variable named RUNPOD_ASSISTANT_BASE_URL with the Mastra endpoint URL"
-            exit 1
-          fi
-
-          if [ -z "${RUNPOD_ASSISTANT_API_KEY:-}" ]; then
-            echo "::error::RUNPOD_ASSISTANT_API_KEY is not configured"
-            echo ""
-            echo "To fix: Go to Settings > Secrets and variables > Actions > Secrets"
-            echo "Add a secret named RUNPOD_ASSISTANT_API_KEY with the API key"
-            exit 1
-          fi
-
-          RUN_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
-          echo "Run ID: $RUN_ID"
-
-          make_request() {
-            local endpoint="$1"
-            local data="$2"
-            local step_name="$3"
-
-            echo "$step_name..."
-            response=$(curl -s -w "\n%{http_code}" --max-time 30 -X POST \
-              "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/ingestDocsWorkflow/${endpoint}?runId=$RUN_ID" \
-              -H "Content-Type: application/json" \
-              -H "Authorization: Bearer ${RUNPOD_ASSISTANT_API_KEY}" \
-              -d "$data")
-
-            http_code=$(echo "$response" | tail -n1)
-            body=$(echo "$response" | sed '$d')
-
-            if [ "$http_code" -eq 200 ]; then
-              echo "Success: $body"
-              return 0
-            fi
-
-            # Provide specific error messages based on HTTP status
-            echo "::error::$step_name failed with HTTP $http_code"
-            echo ""
-            echo "Response body: $body"
-            echo ""
-
-            case "$http_code" in
-              401|403)
-                echo "Cause: Authentication failed"
-                echo "To fix: Verify RUNPOD_ASSISTANT_API_KEY is correct in repository secrets"
-                ;;
-              404)
-                echo "Cause: Workflow 'ingestDocsWorkflow' not found"
-                echo "To fix: Verify the workflow is deployed at ${RUNPOD_ASSISTANT_BASE_URL}"
-                ;;
-              500|502|503|504)
-                echo "Cause: Server error at ${RUNPOD_ASSISTANT_BASE_URL}"
-                echo "To fix: Check if runpod-assistant is healthy; retry the workflow"
-                ;;
-              *)
-                echo "Cause: Unexpected error"
-                echo "To fix: Check the response body above for details"
-                ;;
-            esac
-
-            exit 1
-          }
-
-          make_request "create-run" '{}' "Creating workflow run"
-          make_request "start" '{"inputData": {"branch": "main"}}' "Starting workflow run"
-
-          echo ""
-          echo "Successfully triggered docs ingestion workflow"
+        run: .github/scripts/trigger-ingestion.sh

From 2e5d590c657800804319e243b7dd8bbea3504212 Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Wed, 4 Feb 2026 15:33:45 -0500
Subject: [PATCH 6/7] fix: use secrets for both env vars instead of vars

---
 .github/scripts/trigger-ingestion.sh         | 9 ++++-----
 .github/workflows/trigger-docs-ingestion.yml | 4 ++--
 2 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/.github/scripts/trigger-ingestion.sh b/.github/scripts/trigger-ingestion.sh
index 1ca8ee3d..de265663 100755
--- a/.github/scripts/trigger-ingestion.sh
+++ b/.github/scripts/trigger-ingestion.sh
@@ -25,13 +25,12 @@ log_error() { echo "::error::$*"; }
 
 check_required_var() {
     local var_name="$1"
-    local fix_location="$2"
 
     if [ -z "${!var_name:-}" ]; then
         log_error "$var_name is not configured"
         log ""
-        log "To fix: Go to Settings > Secrets and variables > Actions > $fix_location"
-        log "Add: $var_name"
+        log "To fix: Go to Settings > Secrets and variables > Actions > Secrets"
+        log "Add a secret named: $var_name"
         exit 1
     fi
     log_ok "$var_name is configured"
@@ -112,8 +111,8 @@ main() {
 
     # Validate required environment variables
     log "Checking configuration..."
-    check_required_var "RUNPOD_ASSISTANT_BASE_URL" "Variables"
-    check_required_var "RUNPOD_ASSISTANT_API_KEY" "Secrets"
+    check_required_var "RUNPOD_ASSISTANT_BASE_URL"
+    check_required_var "RUNPOD_ASSISTANT_API_KEY"
     log ""
 
     # Generate unique run ID
diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
index 6ac3eb65..c43659fd 100644
--- a/.github/workflows/trigger-docs-ingestion.yml
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -31,7 +31,7 @@ jobs:
 
       - name: Validate configuration
         env:
-          RUNPOD_ASSISTANT_BASE_URL: ${{ vars.RUNPOD_ASSISTANT_BASE_URL }}
+          RUNPOD_ASSISTANT_BASE_URL: ${{ secrets.RUNPOD_ASSISTANT_BASE_URL }}
           RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
           VALIDATE_ONLY: "true"
         run: .github/scripts/trigger-ingestion.sh
@@ -45,6 +45,6 @@ jobs:
 
       - name: Trigger docs ingestion
         env:
-          RUNPOD_ASSISTANT_BASE_URL: ${{ vars.RUNPOD_ASSISTANT_BASE_URL }}
+          RUNPOD_ASSISTANT_BASE_URL: ${{ secrets.RUNPOD_ASSISTANT_BASE_URL }}
           RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
         run: .github/scripts/trigger-ingestion.sh

From 827847cb624a563c98b10ea4237d7ce6c2cb9bf5 Mon Sep 17 00:00:00 2001
From: Justin Lin <justinwlin@gmail.com>
Date: Thu, 5 Feb 2026 13:16:11 -0500
Subject: [PATCH 7/7] chore: rename RUNPOD_ASSISTANT_BASE_URL to
 RUNPOD_ASSISTANT_API_URL

Use consistent naming with main-ui/console.
---
 .github/scripts/trigger-ingestion.sh         | 8 ++++----
 .github/workflows/trigger-docs-ingestion.yml | 4 ++--
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/.github/scripts/trigger-ingestion.sh b/.github/scripts/trigger-ingestion.sh
index de265663..c6ae4d27 100755
--- a/.github/scripts/trigger-ingestion.sh
+++ b/.github/scripts/trigger-ingestion.sh
@@ -4,7 +4,7 @@
 # Used by GitHub Actions to sync documentation changes.
 #
 # Required environment variables:
-#   RUNPOD_ASSISTANT_BASE_URL - Base URL of the assistant API
+#   RUNPOD_ASSISTANT_API_URL - Base URL of the assistant API
 #   RUNPOD_ASSISTANT_API_KEY  - API key for authentication
 #
 # Optional:
@@ -52,7 +52,7 @@ api_request() {
     response=$(curl -s -w "\nHTTP_STATUS:%{http_code}" \
         --max-time "$TIMEOUT_SECONDS" \
         -X POST \
-        "${RUNPOD_ASSISTANT_BASE_URL}/api/workflows/${WORKFLOW_ID}/${endpoint}" \
+        "${RUNPOD_ASSISTANT_API_URL}/api/workflows/${WORKFLOW_ID}/${endpoint}" \
         -H "Content-Type: application/json" \
         -H "Authorization: Bearer ${RUNPOD_ASSISTANT_API_KEY}" \
         -d "$data")
@@ -82,7 +82,7 @@ api_request() {
             log "Response: $response"
             log ""
             log "Cause: Workflow '$WORKFLOW_ID' doesn't exist at this endpoint"
-            log "To fix: Verify workflow is deployed at $RUNPOD_ASSISTANT_BASE_URL"
+            log "To fix: Verify workflow is deployed at $RUNPOD_ASSISTANT_API_URL"
             return 1
             ;;
         500|502|503|504)
@@ -111,7 +111,7 @@ main() {
 
     # Validate required environment variables
     log "Checking configuration..."
-    check_required_var "RUNPOD_ASSISTANT_BASE_URL"
+    check_required_var "RUNPOD_ASSISTANT_API_URL"
     check_required_var "RUNPOD_ASSISTANT_API_KEY"
     log ""
 
diff --git a/.github/workflows/trigger-docs-ingestion.yml b/.github/workflows/trigger-docs-ingestion.yml
index c43659fd..0c1b12e1 100644
--- a/.github/workflows/trigger-docs-ingestion.yml
+++ b/.github/workflows/trigger-docs-ingestion.yml
@@ -31,7 +31,7 @@ jobs:
 
       - name: Validate configuration
         env:
-          RUNPOD_ASSISTANT_BASE_URL: ${{ secrets.RUNPOD_ASSISTANT_BASE_URL }}
+          RUNPOD_ASSISTANT_API_URL: ${{ secrets.RUNPOD_ASSISTANT_API_URL }}
           RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
           VALIDATE_ONLY: "true"
         run: .github/scripts/trigger-ingestion.sh
@@ -45,6 +45,6 @@ jobs:
 
       - name: Trigger docs ingestion
         env:
-          RUNPOD_ASSISTANT_BASE_URL: ${{ secrets.RUNPOD_ASSISTANT_BASE_URL }}
+          RUNPOD_ASSISTANT_API_URL: ${{ secrets.RUNPOD_ASSISTANT_API_URL }}
           RUNPOD_ASSISTANT_API_KEY: ${{ secrets.RUNPOD_ASSISTANT_API_KEY }}
         run: .github/scripts/trigger-ingestion.sh