Docs Deployment Reliability Checklist

Issue: BUY-3441
Scope: API docs and developer pages deployed via MkDocs + GitHub Pages
Purpose: Ensure docs deployments are reliable with verified URLs, cache invalidation, and rollback handling
Last Updated: 2026-04-19
Status: ACTIVE

---

Overview

Docs are deployed via GitHub Actions (.github/workflows/docs.yml) on push to master when docs/**, mkdocs.yml, or the workflow itself changes. Built site is served at https://docs.buywhere.ai/.

Scope: Proxy-free (no Cloudflare/proxy cache layers), launch-relevant checks only.

---

Pre-Deployment Checks

[ ] 1. MkDocs Build Validation

• Run mkdocs build locally and verify no errors
• Check for broken internal links: mkdocs build --strict (if available)
• Verify site_name and site_url in mkdocs.yml are correct
• Confirm nav structure renders correctly

[ ] 2. Content Validation

• Run link checker on docs directory before build
• Verify OpenAPI spec paths are valid: docs/api-reference/openapi.md
• Check for any hardcoded URLs that may be stale
• Validate Markdown syntax and rendering

[ ] 3. Git Status Verification

• Confirm only intended docs files are changed
• Check that mkdocs.yml changes are intentional
• Verify no sensitive content accidentally committed

[ ] 4. GitHub Actions Permissions

• Confirm deploy-pages workflow has required permissions:
  • contents: read
  • pages: write
  • id-token: write
• Verify workflow concurrency settings won't cause issues

---

Post-Deployment Verification (0-15 minutes)

[ ] 5. URL Verification

After GitHub Actions completes, verify each key URL:

# Automated URL verification script
for url in \
  "https://docs.buywhere.ai/" \
  "https://docs.buywhere.ai/getting-started/" \
  "https://docs.buywhere.ai/quickstart/" \
  "https://docs.buywhere.ai/api-reference/openapi/" \
  "https://docs.buywhere.ai/pricing/" \
  "https://docs.buywhere.ai/changelog/"; do
  status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
  echo "$url -> $status"
done

[ ] 6. GitHub Pages Deployment Status

• Check Actions run: https://github.com/buywhere/buywhere-api/actions
• Verify deploy-pages job succeeded
• Confirm deployment URL in Actions logs matches https://docs.buywhere.ai/

[ ] 7. Navigation Verification

• Test tab navigation (top-level nav)
• Verify sidebar navigation works on all major sections
• Confirm search functionality returns results

[ ] 8. Content Rendering Check

• Verify code blocks render with syntax highlighting
• Check that admonitions (notes, warnings) display correctly
• Confirm OpenAPI/Swagger UI renders if applicable
• Verify dark/light mode toggle works

---

Cache Invalidation

[ ] 9. GitHub Pages Cache

• GitHub Pages serves directly from main branch's site/ directory
• Cache is automatically invalidated on new deployment
• No manual purge needed for standard GitHub Pages

[ ] 10. Browser Cache Verification

• Force-refresh (Ctrl+Shift+R / Cmd+Shift+R) on key pages
• Verify content reflects latest commit (check a recently changed page)
• Test in incognito/private window to confirm fresh load

[ ] 11. CDN Considerations (if later added)

Remaining Risk: If a CDN (Cloudflare, Fastly) is added in front of GitHub Pages:

• Document CDN cache purge procedure here
• Add CDN purge step to GitHub Actions workflow
• Verify cache headers on responses (Cache-Control, ETag)

---

Rollback Handling

[ ] 12. GitHub Pages Rollback

Rollback is accomplished by re-deploying a previous commit.

# Option A: Revert master and push
git revert HEAD
git push origin master

# Option B: Manually trigger previous successful workflow
# 1. Go to Actions tab
# 2. Find last successful "Deploy Docs to GitHub Pages" run
# 3. Click "Re-run jobs"

[ ] 13. Rollback Verification After Revert

After rollback:

• Confirm https://docs.buywhere.ai/ loads correct (old) content
• Verify specific pages that were changed are reverted
• Check Actions run shows new deployment with reverted content
• Confirm GitHub Pages shows correct deployment timestamp

[ ] 14. Rollback Time Estimate

• GitHub Pages deployment typically takes 1-3 minutes
• Full rollback cycle (revert + deploy)预计: 5-10 minutes
• Document any blockers or delays observed

---

Smoke Test Script

#!/bin/bash
# docs-smoke-test.sh - Run after docs deployment

BASE_URL="https://docs.buywhere.ai"
FAILED=0

urls=(
  "/"
  "/getting-started/"
  "/quickstart/"
  "/api-reference/openapi/"
  "/pricing/"
  "/changelog/"
)

for url in "${urls[@]}"; do
  full_url="${BASE_URL}${url}"
  status=$(curl -s -o /dev/null -w "%{http_code}" "$full_url")
  if [ "$status" = "200" ]; then
    echo "✓ $full_url"
  else
    echo "✗ $full_url (status: $status)"
    FAILED=1
  fi
done

# Check search works (should return 200, content not empty)
search_status=$(curl -s -o /dev/null -w "%{http_code}" "${BASE_URL}/search/search_index.json")
if [ "$search_status" = "200" ]; then
  echo "✓ Search index available"
else
  echo "✗ Search index (status: $search_status)"
  FAILED=1
fi

exit $FAILED

---

Validation Results

Notes on Validation Results

Use this section to document any issues found during validation runs.

---

Remaining Risks

---

Emergency Contacts

---

References

• MkDocs Documentation
• GitHub Actions Deploy Pages
• BuyWhere API Docs Repository
• Docs Deployment Workflow

---

End of Document