From f84e9ef211527daf0970e34af8c4793cc5f01e96 Mon Sep 17 00:00:00 2001 From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com> Date: Sat, 6 Jun 2026 18:06:36 +0200 Subject: [PATCH 1/4] docs(environment-setup): reconcile machine sizing with the preflight gate (#54) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The installer now hard-fails below ~5 GB RAM on Linux (was warn-only), so the old "it only warns" line was wrong. State minimum-to-run (2 CPU / 5 GB / 10 GB) vs recommended-to-train (4 CPU / 16 GB / 50 GB) consistently across quickstart, deploy-local, and the setup guide. A single training job reserves ~8 GB. Pairs with tracebloc/client#217 · refs tracebloc/backend#744 Co-authored-by: Claude Opus 4.8 --- environment-setup/deploy-local.mdx | 2 +- environment-setup/quickstart.mdx | 4 ++-- environment-setup/setup-guide.mdx | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/environment-setup/deploy-local.mdx b/environment-setup/deploy-local.mdx index 2fa8e21..82f22a8 100644 --- a/environment-setup/deploy-local.mdx +++ b/environment-setup/deploy-local.mdx @@ -7,7 +7,7 @@ description: "Run a tracebloc workspace on a single machine — laptop or on-pre ## Prerequisites -- A machine: macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk. +- A machine: macOS, Linux, or Windows · 2 CPU · 5 GB RAM · 10 GB free disk to run (4 CPU · 16 GB · 50 GB to train on it). - Your **Client ID** and password from the [clients page](https://ai.tracebloc.io/clients). That's it — no Docker or Kubernetes knowledge needed. The installer sets up Docker and the cluster for you. diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx index 333e179..dd5622d 100644 --- a/environment-setup/quickstart.mdx +++ b/environment-setup/quickstart.mdx @@ -13,10 +13,10 @@ A running workspace in about 10 minutes, with one command. Deploying on a specif | You need | Minimum | |---|---| -| A machine | macOS, Linux, or Windows · 2 CPU · 4 GB RAM · 20 GB free disk | +| A machine | macOS, Linux, or Windows · 2 CPU · 5 GB RAM · 10 GB free disk | | A tracebloc account | [Sign up free](https://ai.tracebloc.io) — no credit card | -The installer runs below these too — it only warns, and more RAM mainly helps once models train. +That's enough to run a workspace. To **train on this machine**, give it 4 CPU · 16 GB RAM · 50 GB disk — a single training job alone reserves ~8 GB. The installer checks before it starts: below the minimum it stops on Linux (on macOS/Windows it warns — raise Docker Desktop's memory in Settings → Resources). diff --git a/environment-setup/setup-guide.mdx b/environment-setup/setup-guide.mdx index a9eb9bb..4a0fffd 100644 --- a/environment-setup/setup-guide.mdx +++ b/environment-setup/setup-guide.mdx @@ -13,13 +13,13 @@ The installer deploys a **single-node workspace on one machine** — a local Kub ## Requirements -The installer runs on any modern machine (one host per workspace). These are the minimum specs to run a workspace comfortably: +The installer runs on any modern machine (one host per workspace) and **checks these before it starts** — below the minimum it stops on Linux with a clear message (on macOS/Windows it warns; raise Docker Desktop's memory in Settings → Resources). "To run" keeps a workspace online; **training on the same machine needs the headroom** — a single training job alone reserves ~8 GB. -| | Minimum | Recommended | +| | To run the workspace | To train on this machine | |---|---------|-------------| -| **CPU** | 2 cores | 8+ cores | -| **RAM** | 4 GB | 16+ GB | -| **Disk** | 20 GB free | 50+ GB free | +| **CPU** | 2 cores | 4+ cores | +| **RAM** | 5 GB | 16 GB | +| **Disk** | 10 GB free | 50+ GB free | **Supported platforms:** macOS (Intel & Apple Silicon) · Linux (x86_64 & arm64) · Windows (x86_64 & arm64) From 0aa45595d7ec2d72596895ea1083da7a9a1c3520 Mon Sep 17 00:00:00 2001 From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com> Date: Sat, 6 Jun 2026 18:39:21 +0200 Subject: [PATCH 2/4] chore(docs): touch all .mdx files to force Mintlify full rebuild (#55) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mintlify dev preview at tracebloc-develop.mintlify.app was returning 404 on every page that wasn't part of a recent incremental build. Confirmed by curl: the 3 paths touched by #54 returned 200, all others 404. Adding a trailing newline to all 31 .mdx files marks them as changed in git so Mintlify's incremental builder treats every page as needing update, restoring full dev preview coverage. No content change — just file-mtime/hash bump. Co-authored-by: Claude Opus 4.7 (1M context) --- create-use-case/define.mdx | 1 + create-use-case/evaluate-models.mdx | 1 + create-use-case/prepare-dataset.mdx | 1 + create-use-case/prerequisites.mdx | 1 + create-use-case/templates.mdx | 1 + environment-setup/cli.mdx | 1 + environment-setup/configuration.mdx | 1 + environment-setup/deploy-aks.mdx | 1 + environment-setup/deploy-bare-metal.mdx | 1 + environment-setup/deploy-local.mdx | 1 + environment-setup/deploy-openshift.mdx | 1 + environment-setup/deployment-environments.mdx | 1 + environment-setup/eks-client-deployment-guide.mdx | 1 + environment-setup/operations.mdx | 1 + environment-setup/overview.mdx | 1 + environment-setup/quickstart.mdx | 1 + environment-setup/security.mdx | 1 + environment-setup/setup-guide.mdx | 1 + environment-setup/troubleshooting.mdx | 1 + join-use-case/explore-use-case.mdx | 1 + join-use-case/how-training-works.mdx | 1 + join-use-case/hyperparameters.mdx | 2 +- join-use-case/join-use-case.mdx | 1 + join-use-case/model-evaluation.mdx | 1 + join-use-case/model-optimization.mdx | 1 + join-use-case/overview.mdx | 1 + join-use-case/start-training.mdx | 2 +- overview/tracebloc.mdx | 2 +- tools-help/faqs.mdx | 1 + tools-help/key-terms.mdx | 1 + tools-help/tracebloc.mdx | 1 + 31 files changed, 31 insertions(+), 3 deletions(-) diff --git a/create-use-case/define.mdx b/create-use-case/define.mdx index 785ed54..0e46f04 100644 --- a/create-use-case/define.mdx +++ b/create-use-case/define.mdx @@ -255,3 +255,4 @@ Once models have been submitted, you can [compare them in the leaderboard sectio ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/evaluate-models.mdx b/create-use-case/evaluate-models.mdx index d2fd154..f700b89 100644 --- a/create-use-case/evaluate-models.mdx +++ b/create-use-case/evaluate-models.mdx @@ -49,3 +49,4 @@ Scores on the leaderboard are calculated using the metric you selected when defi ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/prepare-dataset.mdx b/create-use-case/prepare-dataset.mdx index aee27d7..872891c 100644 --- a/create-use-case/prepare-dataset.mdx +++ b/create-use-case/prepare-dataset.mdx @@ -597,3 +597,4 @@ kubectl get pvc -n ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/prerequisites.mdx b/create-use-case/prerequisites.mdx index eeb166a..cb9c8d9 100644 --- a/create-use-case/prerequisites.mdx +++ b/create-use-case/prerequisites.mdx @@ -275,3 +275,4 @@ This product is amazing! I love it. ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/create-use-case/templates.mdx b/create-use-case/templates.mdx index 72ac550..cf20000 100644 --- a/create-use-case/templates.mdx +++ b/create-use-case/templates.mdx @@ -35,3 +35,4 @@ For real examples already running on the platform, see the [explore section on t ## Need help? Email [support@tracebloc.io](mailto:support@tracebloc.io). + diff --git a/environment-setup/cli.mdx b/environment-setup/cli.mdx index ff83ae5..a463434 100644 --- a/environment-setup/cli.mdx +++ b/environment-setup/cli.mdx @@ -99,3 +99,4 @@ Both submit to the same ingestion protocol — pick the one that fits your workf ## Coming soon Cloud-source ingestion (S3 / GCS / HTTPS) for large datasets, a `dataset list` verb, and `semantic_segmentation` support. + diff --git a/environment-setup/configuration.mdx b/environment-setup/configuration.mdx index 6e2544b..ffd9a31 100644 --- a/environment-setup/configuration.mdx +++ b/environment-setup/configuration.mdx @@ -447,3 +447,4 @@ Tracebloc is designed so your data never has to leave your network. Here's how: - **Isolated.** Training runs in containers with restricted system access. Kubernetes namespaces separate workloads from each other. - **Scanned.** Submitted models are analyzed for vulnerabilities before execution on your infrastructure. - **Minimal footprint.** The installer only modifies `~/.tracebloc/` and Docker. No system-wide changes. + diff --git a/environment-setup/deploy-aks.mdx b/environment-setup/deploy-aks.mdx index d4b4041..bda4805 100644 --- a/environment-setup/deploy-aks.mdx +++ b/environment-setup/deploy-aks.mdx @@ -52,3 +52,4 @@ clusterScope: true - Use GPU node pools for training workloads; size requests/limits per job. - Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations). + diff --git a/environment-setup/deploy-bare-metal.mdx b/environment-setup/deploy-bare-metal.mdx index 222d1b9..37a63ab 100644 --- a/environment-setup/deploy-bare-metal.mdx +++ b/environment-setup/deploy-bare-metal.mdx @@ -56,3 +56,4 @@ clusterScope: true - Schedule MySQL and storage on reliable nodes; back up the data PVCs. - Size training compute per job via `RESOURCE_REQUESTS` / `RESOURCE_LIMITS` ([Configuration](/environment-setup/configuration#resource-limits-for-training-jobs)). - Day-2 upgrades and rollbacks: see [Operations](/environment-setup/operations). + diff --git a/environment-setup/deploy-local.mdx b/environment-setup/deploy-local.mdx index 82f22a8..1d9f297 100644 --- a/environment-setup/deploy-local.mdx +++ b/environment-setup/deploy-local.mdx @@ -53,3 +53,4 @@ GPUs are auto-detected on Linux (NVIDIA/AMD) — drivers, container toolkit, and - Your data persists in `HOST_DATA_DIR` across stop/start cycles (see [Operations](/environment-setup/operations)). - Need more headroom? Re-run the installer on a bigger machine, or add worker nodes with `AGENTS`. - For multi-node high availability, use [bare-metal](/environment-setup/deploy-bare-metal) or a managed cloud instead. + diff --git a/environment-setup/deploy-openshift.mdx b/environment-setup/deploy-openshift.mdx index e594f0c..15aa5d2 100644 --- a/environment-setup/deploy-openshift.mdx +++ b/environment-setup/deploy-openshift.mdx @@ -56,3 +56,4 @@ networkPolicy: - The bundled SCC grants the resource-monitor the host access it needs — review it against your cluster policy. - Size training compute per job; day-2 management is in [Operations](/environment-setup/operations). + diff --git a/environment-setup/deployment-environments.mdx b/environment-setup/deployment-environments.mdx index d3fc419..4298716 100644 --- a/environment-setup/deployment-environments.mdx +++ b/environment-setup/deployment-environments.mdx @@ -26,3 +26,4 @@ Each guide follows the same six headings, so you always know where to look: **When to pick it · Prerequisites · Install · Verify · Environment-specific config · Production notes.** Adding a new target later (GKE, on-prem k3s, …) means filling the same template. All environments deploy the same chart — see [Configuration](/environment-setup/configuration) for every value, and [Operations](/environment-setup/operations) for day-2 management. + diff --git a/environment-setup/eks-client-deployment-guide.mdx b/environment-setup/eks-client-deployment-guide.mdx index 2341c0c..dd4c07d 100644 --- a/environment-setup/eks-client-deployment-guide.mdx +++ b/environment-setup/eks-client-deployment-guide.mdx @@ -865,3 +865,4 @@ kubectl delete namespace - Email: [support@tracebloc.io](mailto:support@tracebloc.io) - Docs: [tracebloc Documentation Portal](https://docs.tracebloc.io) + diff --git a/environment-setup/operations.mdx b/environment-setup/operations.mdx index 3f57c13..28a6255 100644 --- a/environment-setup/operations.mdx +++ b/environment-setup/operations.mdx @@ -83,3 +83,4 @@ PVCs are annotated `helm.sh/resource-policy: keep`, so your data survives an uni ## Back up Your data lives in the data PVCs (or `~/.tracebloc` on a local install). Back up that directory / those volumes on your normal schedule — tracebloc keeps nothing of yours off your infrastructure. + diff --git a/environment-setup/overview.mdx b/environment-setup/overview.mdx index 1941f1a..674c82a 100644 --- a/environment-setup/overview.mdx +++ b/environment-setup/overview.mdx @@ -79,3 +79,4 @@ The installer changes only **Docker** and **`~/.tracebloc`** on your host — no Want the guarantees in detail for your security team? See [Security & data handling](/environment-setup/configuration#security). + diff --git a/environment-setup/quickstart.mdx b/environment-setup/quickstart.mdx index dd5622d..0fb50f1 100644 --- a/environment-setup/quickstart.mdx +++ b/environment-setup/quickstart.mdx @@ -79,3 +79,4 @@ If your security policy forbids piping scripts from the internet, skip the one-l Define a task and invite contributors. + diff --git a/environment-setup/security.mdx b/environment-setup/security.mdx index 4aacded..2e3992d 100644 --- a/environment-setup/security.mdx +++ b/environment-setup/security.mdx @@ -35,3 +35,4 @@ If support asks for diagnostics, `--diagnose` produces a bundle with **credentia ## Outbound access Your workspace needs outbound HTTPS to: `*.docker.io`, `ghcr.io`, `raw.githubusercontent.com`, `*.github.io`, `*.tracebloc.io`, and `pypi.org`. Nothing needs to reach *in*. + diff --git a/environment-setup/setup-guide.mdx b/environment-setup/setup-guide.mdx index 4a0fffd..72d764b 100644 --- a/environment-setup/setup-guide.mdx +++ b/environment-setup/setup-guide.mdx @@ -163,3 +163,4 @@ Your workspace is running. Here's where to go from here: **Data scientists:** [Join a use case](/join-use-case/join-use-case) — connect to a workspace, train models on real data, and submit results. **Advanced configuration:** [Configuration](/environment-setup/configuration) — customize installer options, manage the cluster, configure GPU settings, or deploy manually with Helm. + diff --git a/environment-setup/troubleshooting.mdx b/environment-setup/troubleshooting.mdx index f2fd0ce..efee42b 100644 --- a/environment-setup/troubleshooting.mdx +++ b/environment-setup/troubleshooting.mdx @@ -109,3 +109,4 @@ If training is slow, these are the factors to look at: - **Precision** — FP16/BF16 can speed up training 2-3x on modern GPUs - **Data pipeline** — slow CPU preprocessing (augmentation, tokenization) can bottleneck training - **Parallelization** — data parallelism splits batches across GPUs; model parallelism splits the model itself + diff --git a/join-use-case/explore-use-case.mdx b/join-use-case/explore-use-case.mdx index e20d23c..e8ebe1c 100644 --- a/join-use-case/explore-use-case.mdx +++ b/join-use-case/explore-use-case.mdx @@ -95,3 +95,4 @@ Learn how to [join a use case](/join-use-case/join-use-case) and get started wit ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/how-training-works.mdx b/join-use-case/how-training-works.mdx index ab0d252..44e1468 100644 --- a/join-use-case/how-training-works.mdx +++ b/join-use-case/how-training-works.mdx @@ -528,3 +528,4 @@ To validate a result you saw on the platform: If a number on your end doesn't line up with what the platform reports, please [contact us](mailto:support@tracebloc.io) so we can investigate together. + diff --git a/join-use-case/hyperparameters.mdx b/join-use-case/hyperparameters.mdx index 338511c..024130e 100644 --- a/join-use-case/hyperparameters.mdx +++ b/join-use-case/hyperparameters.mdx @@ -211,4 +211,4 @@ For more info about available functions and methods, call the help function in y user.help() ``` -- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) \ No newline at end of file +- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) diff --git a/join-use-case/join-use-case.mdx b/join-use-case/join-use-case.mdx index da9297c..e451e3c 100644 --- a/join-use-case/join-use-case.mdx +++ b/join-use-case/join-use-case.mdx @@ -35,3 +35,4 @@ To invite others to your team: ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/model-evaluation.mdx b/join-use-case/model-evaluation.mdx index 19c62f5..de5ae2b 100644 --- a/join-use-case/model-evaluation.mdx +++ b/join-use-case/model-evaluation.mdx @@ -37,3 +37,4 @@ Contributors are ranked by their best performing model score on the test data. C ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/model-optimization.mdx b/join-use-case/model-optimization.mdx index 2f986c0..56ecde7 100644 --- a/join-use-case/model-optimization.mdx +++ b/join-use-case/model-optimization.mdx @@ -348,3 +348,4 @@ The main file should contain the variable values as mentioned in type 2 format. ## Need Help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/overview.mdx b/join-use-case/overview.mdx index c43dd85..cae5a74 100644 --- a/join-use-case/overview.mdx +++ b/join-use-case/overview.mdx @@ -53,3 +53,4 @@ Once training is complete, you select your best performing cycle and submit it f ## Need help? - Email us at [support@tracebloc.io](mailto:support@tracebloc.io) + diff --git a/join-use-case/start-training.mdx b/join-use-case/start-training.mdx index 63c22ac..7963246 100644 --- a/join-use-case/start-training.mdx +++ b/join-use-case/start-training.mdx @@ -244,4 +244,4 @@ For more info about available functions and methods, call the help function in y user.help() ``` -- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) \ No newline at end of file +- Email us at [support@tracebloc.io](mailto:support@tracebloc.io) diff --git a/overview/tracebloc.mdx b/overview/tracebloc.mdx index bae2230..0e4fd97 100644 --- a/overview/tracebloc.mdx +++ b/overview/tracebloc.mdx @@ -119,4 +119,4 @@ tracebloc is a **collaborative AI workspace** you deploy on your own infrastruct GPU configuration, Helm deployment, EKS. - \ No newline at end of file + diff --git a/tools-help/faqs.mdx b/tools-help/faqs.mdx index de77be4..c2d3ce8 100644 --- a/tools-help/faqs.mdx +++ b/tools-help/faqs.mdx @@ -61,3 +61,4 @@ See the [pricing page](https://tracebloc.io/#pricing) on the website. - [Get started](/environment-setup/setup-guide) — install the client - [Browse key terms](/tools-help/key-terms) - [Use the Python SDK](/tools-help/tracebloc) + diff --git a/tools-help/key-terms.mdx b/tools-help/key-terms.mdx index 1cf8766..2c9ae6b 100644 --- a/tools-help/key-terms.mdx +++ b/tools-help/key-terms.mdx @@ -46,3 +46,4 @@ The process of adjusting a pre-trained model for a specific task. - [Check FAQs](/tools-help/faqs) - [Review SDK documentation](/tools-help/tracebloc) + diff --git a/tools-help/tracebloc.mdx b/tools-help/tracebloc.mdx index c3874f5..230879c 100644 --- a/tools-help/tracebloc.mdx +++ b/tools-help/tracebloc.mdx @@ -79,3 +79,4 @@ The fastest way to get started is our [Google Colab notebook](https://colab.rese - [Hyperparameters](/join-use-case/hyperparameters) — full reference for all training configuration options - [FAQs](/tools-help/faqs) - [Key terms](/tools-help/key-terms) + From f6bb9e0e964a2cb38ae17614c3100434ec629808 Mon Sep 17 00:00:00 2001 From: lukasWuttke <54042461+LukasWodka@users.noreply.github.com> Date: Mon, 8 Jun 2026 09:02:03 +0200 Subject: [PATCH 3/4] ci(docs): nightly + on-push probe for page coverage on dev and prod (#56) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Catches the failure mode that bit us on 2026-06-06: Mintlify's incremental build pipeline silently left the dev preview at tracebloc-develop.mintlify.app serving 404s on most pages for days. Mintlify's own deploy check reported "success" every time — only an end-to-end HTTP probe of each declared page would have detected the gap. The new workflow: - Parses docs.json to extract every page path referenced in navigation - GETs each path on dev preview and prod docs site (parallel matrix) - Fails the job if any page returns non-200 - Reports broken paths in the workflow summary with the likely fix (touch all .mdx files to force Mintlify full rebuild) Triggers: - schedule: 06:00 UTC daily (catches Mintlify state drift) - push to develop / main (catches build regressions immediately, with a 120s wait for Mintlify deploy to complete) - workflow_dispatch with env=dev|prod|both for manual reruns Reference: docs PR #55 (the force-rebuild fix that surfaced this gap). Co-authored-by: Claude Opus 4.7 (1M context) --- .github/workflows/preview-page-coverage.yml | 154 ++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 .github/workflows/preview-page-coverage.yml diff --git a/.github/workflows/preview-page-coverage.yml b/.github/workflows/preview-page-coverage.yml new file mode 100644 index 0000000..1ca820d --- /dev/null +++ b/.github/workflows/preview-page-coverage.yml @@ -0,0 +1,154 @@ +name: Docs preview page coverage + +# Verifies that every page declared in docs.json's navigation is reachable +# (HTTP 200) on both the dev preview and prod docs site. +# +# Catches the failure mode from 2026-06-06: Mintlify's incremental builder +# left tracebloc-develop.mintlify.app with most pages returning 404 for days +# because the full-page index was wiped and only files touched by subsequent +# commits got re-rendered. Mintlify's own check reported "deploy success" +# every time. This workflow probes the actual rendered URLs and fails the +# build if any page is missing. +# +# Trigger: +# - schedule: daily 06:00 UTC (catches Mintlify state drift) +# - push: to develop / main (catches build regressions immediately) +# - workflow_dispatch: manual rerun +# +# After a push, waits 120s for Mintlify's deploy to complete before probing. + +on: + schedule: + - cron: '0 6 * * *' + push: + branches: [develop, main] + workflow_dispatch: + inputs: + env: + description: "Which environment to probe (default: both)" + type: choice + options: [both, dev, prod] + default: both + +permissions: + contents: read + +concurrency: + group: docs-coverage-${{ github.ref }} + cancel-in-progress: false + +jobs: + resolve-env: + runs-on: ubuntu-latest + outputs: + matrix: ${{ steps.set.outputs.matrix }} + steps: + - id: set + env: + CHOICE: ${{ github.event.inputs.env || 'both' }} + run: | + case "$CHOICE" in + dev) m='[{"name":"dev","url":"https://tracebloc-develop.mintlify.app"}]' ;; + prod) m='[{"name":"prod","url":"https://docs.tracebloc.io"}]' ;; + both|*) m='[{"name":"dev","url":"https://tracebloc-develop.mintlify.app"},{"name":"prod","url":"https://docs.tracebloc.io"}]' ;; + esac + echo "matrix=$m" >> "$GITHUB_OUTPUT" + + probe: + needs: resolve-env + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + env: ${{ fromJSON(needs.resolve-env.outputs.matrix) }} + steps: + - uses: actions/checkout@v4 + + - name: Wait for Mintlify to deploy (push events only) + if: github.event_name == 'push' + env: + ENV_NAME: ${{ matrix.env.name }} + run: | + # Mintlify's deploy typically completes in 30-90s after push. + # Allow a generous buffer so the probe sees the new state. + if [ "$ENV_NAME" = "prod" ] && [ "$GITHUB_REF_NAME" != "main" ]; then + echo "Push not to main — prod deploy won't run, skipping wait." + elif [ "$ENV_NAME" = "dev" ] && [ "$GITHUB_REF_NAME" != "develop" ]; then + echo "Push not to develop — dev deploy won't run, skipping wait." + else + echo "Waiting 120s for Mintlify ($ENV_NAME) deploy to complete..." + sleep 120 + fi + + - name: Extract every page path from docs.json + run: | + set -euo pipefail + # Walk the entire navigation tree and collect string-valued + # page references. docs.json nests pages under .navigation.tabs[] + # .groups[].pages[] (which can itself recurse). + jq -r ' + [.. | objects | .pages? | values | .[]?] + | map(select(type == "string")) + | unique + | .[] + ' docs.json > /tmp/pages.txt + count=$(wc -l < /tmp/pages.txt | tr -d ' ') + echo "Found $count pages to probe" + if [ "$count" = "0" ]; then + echo "::error::No pages found in docs.json — navigation structure may have changed" + exit 1 + fi + + - name: Probe each page on ${{ matrix.env.name }} + env: + BASE_URL: ${{ matrix.env.url }} + ENV_NAME: ${{ matrix.env.name }} + run: | + set -uo pipefail + : > /tmp/broken.csv + : > /tmp/ok.csv + while IFS= read -r path; do + [ -z "$path" ] && continue + # Follow redirects (-L); cap each request at 15s. + code=$(curl -s -L -o /dev/null -w "%{http_code}" --max-time 15 "$BASE_URL/$path" 2>/dev/null || echo "000") + if [ "$code" = "200" ]; then + echo "/$path,$code" >> /tmp/ok.csv + else + echo "/$path,$code" >> /tmp/broken.csv + echo " ✗ /$path -> HTTP $code" + fi + done < /tmp/pages.txt + + ok=$(wc -l < /tmp/ok.csv | tr -d ' ') + broken=$(wc -l < /tmp/broken.csv | tr -d ' ') + total=$((ok + broken)) + + echo "" + echo "═══ Result on $ENV_NAME: $ok/$total ok, $broken broken ═══" + + { + echo "## $ENV_NAME page coverage" + echo "" + echo "**$total pages probed · $ok ok · $broken broken**" + echo "" + echo "Base URL: \`$BASE_URL\`" + echo "" + if [ "$broken" -gt 0 ]; then + echo "### Broken paths" + echo "" + echo "| Path | HTTP code |" + echo "|---|---|" + awk -F, '{print "| `"$1"` | "$2" |"}' /tmp/broken.csv + echo "" + echo "**Likely cause:** Mintlify incremental builder did not re-render" + echo "these paths. Fix by touching every \`.mdx\` in one commit to" + echo "force a full rebuild (see PR #55 from 2026-06-06)." + else + echo "All pages render correctly. ✓" + fi + } >> "$GITHUB_STEP_SUMMARY" + + if [ "$broken" -gt 0 ]; then + echo "::error::$broken pages on $ENV_NAME returned non-200" + exit 1 + fi From 04e30f212ce3bccae9f639e885dd3d58f53d3d2e Mon Sep 17 00:00:00 2001 From: Lukas Wuttke Date: Mon, 15 Jun 2026 13:35:41 +0200 Subject: [PATCH 4/4] chore(ci): remove fr-gate caller from docs (FR-gate exempt per 2026-06-04) docs was exempted from the FR-gate on 2026-06-04 (content-only, low-risk, may promote develop to main directly). The caller workflow was never removed, so it kept firing "fail" on every develop to main release PR. It is not a required status check and the exemption is intentional. Removing the caller stops the spurious red X on docs release PRs. --- .github/workflows/fr-gate-caller.yml | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 .github/workflows/fr-gate-caller.yml diff --git a/.github/workflows/fr-gate-caller.yml b/.github/workflows/fr-gate-caller.yml deleted file mode 100644 index b725e2c..0000000 --- a/.github/workflows/fr-gate-caller.yml +++ /dev/null @@ -1,15 +0,0 @@ -name: FR gate - -# Per-repo caller. Blocks merges to staging/main/master unless every contained -# kanban item is in "Ready for staging" or "Ready for prod" respectively. -# All logic lives in tracebloc/.github/.github/workflows/fr-gate.yml. - -on: - pull_request: - branches: [staging, main, master] - types: [opened, reopened, synchronize, ready_for_review, labeled, unlabeled] - -jobs: - gate: - uses: tracebloc/.github/.github/workflows/fr-gate.yml@main - secrets: inherit