ci: split agents-docs build into separate workflow#2147
Conversation
The main CI workflow runs all turbo tasks in parallel (concurrency=15) on a 16GB runner. When turbo cache misses cluster, 9+ Node.js processes launch simultaneously — each with a 4GB heap limit — and the Linux OOM killer sends SIGKILL (exit code 137). The agents-docs Next.js build (335 static pages, 3.7min compile) is the heaviest contributor. Since agents-docs is a pure leaf node (nothing depends on it, no tests, deployed separately via Vercel), it can safely build in isolation: - Exclude @inkeep/agents-docs from main CI turbo check - Remove agents-docs build cache step from main CI - Add new ci-docs.yml workflow with path-based triggers - ci-docs builds on ubuntu-latest with 8GB heap (generous for isolation) - Turbo automatically builds transitive deps (agents-core, agents-cli) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
PR Review Summary
(0) Total Issues | Risk: Low
This is a well-structured CI infrastructure change that correctly isolates the heavy agents-docs Next.js build to prevent OOM kills. The implementation follows existing repo patterns for workflow configuration, caching, and permissions.
🔴❗ Critical (0) ❗🔴
None.
🟠⚠️ Major (0) 🟠⚠️
None.
🟡 Minor (0) 🟡
None.
💭 Consider (1) 💭
Inline Comments:
- 💭 Consider:
ci-docs.yml:6-10Self-referential workflow path trigger for self-validation
✅ APPROVE
Summary: This PR is a clean, well-reasoned infrastructure improvement. The workflow split correctly addresses the OOM issue by isolating the heavy docs build with an 8GB heap on ubuntu-latest. Key implementation details are solid: proper permissions (least-privilege), correct concurrency handling (cancels PR runs but preserves scheduled runs), isolated cache keys (turbo-docs- prefix), and appropriate timeout. The one suggestion (self-referential path trigger) is a nice-to-have that would make the workflow self-validating, but the weekly scheduled run provides a fallback validation mechanism. Ship it! 🚀
Discarded (9)
| Location | Issue | Reason Discarded |
|---|---|---|
ci-docs.yml:40-48 |
Action pinning uses mutable tags | Consistent with repo-wide pattern — all 15 workflows use mutable tags |
ci-docs.yml:21-22 |
Permissions block uses least-privilege | Positive observation, not an issue |
ci-docs.yml:24-26 |
Concurrency configuration correct | Positive observation, not an issue |
ci-docs.yml:31-95 |
Timeout and heap size appropriate | Positive observation, not an issue |
ci-docs.yml:69-74 |
Cache key uses docs-specific suffix | Positive observation, not an issue |
ci-docs.yml:85-88 |
Frozen lockfile ensures reproducibility | Positive observation, not an issue |
ci-docs.yml:90-95 |
Turbo filter correctly handles deps | Positive observation, not an issue |
ci.yml:99-104 |
Main CI filter syntax correct | Positive observation, not an issue |
internal-surface-areas/SKILL.md |
Missing new workflow in docs | Out of scope — skill documentation not expected to be updated in every PR |
Reviewers (1)
| Reviewer | Returned | Main Findings | Consider | While You're Here | Inline Comments | Pending Recs | Discarded |
|---|---|---|---|---|---|---|---|
pr-review-devops |
10 | 0 | 0 | 0 | 1 | 0 | 9 |
| Total | 10 | 0 | 0 | 0 | 1 | 0 | 9 |
agents-cli lives at the repo root (agents-cli/), not under packages/. The path 'packages/agents-cli/src/**' would never match, meaning CLI source changes wouldn't trigger the docs CI. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
PR Review Summary
(0) Total Issues | Risk: Low
Delta Review
This is a re-review scoped to the single commit since the last review: fix: correct agents-cli path in ci-docs.yml triggers.
Change: Path triggers updated from packages/agents-cli/src/** → agents-cli/src/** in both push.paths and pull_request.paths.
Verification: ✅ Confirmed correct — agents-cli/ exists at repo root, not under packages/. The previous path would have silently never matched, causing the workflow to skip when CLI changes should have triggered a docs rebuild.
🔴❗ Critical (0) ❗🔴
None.
🟠⚠️ Major (0) 🟠⚠️
None.
🟡 Minor (0) 🟡
None.
💭 Consider (0) 💭
None new. The prior review's suggestion (self-referential workflow path trigger) remains valid but unaddressed — see prior inline comment.
🕐 Pending Recommendations (1)
- 💭
ci-docs.yml:6-10Self-referential workflow path trigger for self-validation
✅ APPROVE
Summary: The delta is a correct bug fix — the original path packages/agents-cli/src/** would never match since agents-cli/ lives at the repo root. This fix ensures CI Docs triggers properly when CLI source changes. The prior review's approval stands; this delta improves the PR. 🚀
Reviewers (0)
| Reviewer | Returned | Main Findings | Consider | While You're Here | Inline Comments | Pending Recs | Discarded |
|---|---|---|---|---|---|---|---|
| orchestrator-only | 0 | 0 | 0 | 0 | 0 | 1 | 0 |
| Total | 0 | 0 | 0 | 0 | 0 | 1 | 0 |
Note: Delta review performed by orchestrator without sub-agent dispatch — trivial path fix verified directly.
The old command was `pnpm check` which resolves turbo via the package scripts. The bare `turbo` command isn't on PATH in CI runners — need `pnpm exec turbo` to resolve the local devDependency. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
PR Review Summary
(0) Total Issues | Risk: Low
Delta Review
This is a re-review scoped to the single commit since the last review: fix: use pnpm exec turbo instead of bare turbo in CI.
Change: Both workflow files updated from turbo → pnpm exec turbo for the turbo command invocations:
ci-docs.yml:92—pnpm exec turbo run build lint typecheck --filter=@inkeep/agents-docsci.yml:104—pnpm exec turbo check --filter='!agents-cookbook-templates' --filter='!@inkeep/agents-docs'
Verification: ✅ Correct improvement — using pnpm exec ensures the locally installed turbo from node_modules/.bin is used explicitly, rather than relying on PATH resolution. This is a best practice for pnpm monorepos and avoids potential issues with global turbo versions or npx-style resolution.
🔴❗ Critical (0) ❗🔴
None.
🟠⚠️ Major (0) 🟠⚠️
None.
🟡 Minor (0) 🟡
None.
💭 Consider (0) 💭
None new. The prior review's suggestion (self-referential workflow path trigger) remains valid but unaddressed — see prior inline comment.
🕐 Pending Recommendations (1)
- 💭
ci-docs.yml:6-10Self-referential workflow path trigger for self-validation
✅ APPROVE
Summary: The delta is a straightforward CI hygiene improvement. Using pnpm exec turbo over bare turbo ensures consistent local package resolution — a minor but sensible refinement. Combined with the previous commits (workflow split + path fix), this PR is ready to ship. 🚀
Reviewers (0)
| Reviewer | Returned | Main Findings | Consider | While You're Here | Inline Comments | Pending Recs | Discarded |
|---|---|---|---|---|---|---|---|
| orchestrator-only | 0 | 0 | 0 | 0 | 0 | 1 | 0 |
| Total | 0 | 0 | 0 | 0 | 0 | 1 | 0 |
Note: Delta review performed by orchestrator without sub-agent dispatch — trivial command invocation fix verified directly.
Addresses review feedback: changes to ci-docs.yml itself now trigger a validation run, making the workflow self-validating rather than relying solely on the weekly cron for workflow file changes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
PR Review Summary
(0) Total Issues | Risk: Low
Delta Review
This is a re-review scoped to the single commit since the last review: ci: add self-referential path trigger for ci-docs workflow.
Change: Added .github/workflows/ci-docs.yml to both push.paths (line 7) and pull_request.paths (line 14).
Verification: ✅ This directly implements the prior Consider recommendation. The workflow is now self-validating — any future changes to ci-docs.yml will automatically trigger a CI run to verify the workflow still works.
🔴❗ Critical (0) ❗🔴
None.
🟠⚠️ Major (0) 🟠⚠️
None.
🟡 Minor (0) 🟡
None.
💭 Consider (0) 💭
None. Prior recommendation addressed.
✅ APPROVE
Summary: This commit completes the PR by addressing the only prior suggestion — adding self-referential path triggers so the workflow validates itself when modified. All four commits together form a clean, well-tested CI improvement. The OOM issue is addressed, the workflow is isolated, paths are correct, and the workflow is self-validating. Ready to merge! 🎉
Reviewers (0)
| Reviewer | Returned | Main Findings | Consider | While You're Here | Inline Comments | Pending Recs | Discarded |
|---|---|---|---|---|---|---|---|
| orchestrator-only | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
| Total | 0 | 0 | 0 | 0 | 0 | 0 | 0 |
Note: Delta review performed by orchestrator without sub-agent dispatch — trivial 2-line change verified directly.
ci-docs.yml now runs only lint+typecheck for agents-docs. Vercel preview already runs `next build` on every PR, so running it again in GHA was duplicate work. This cuts the ci-docs job from ~4min to ~1min and removes the Next.js build cache step (no longer needed). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The separate ci-docs.yml was created to isolate the heavy Next.js SSG build. With build now delegated to Vercel preview, only lint and typecheck remain — lightweight enough to run in the main CI job. The agents-docs build filter stays to prevent OOM. A new step runs lint+typecheck for agents-docs after the main check completes. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
PR Review Summary
(0) Total Issues | Risk: Low
Delta Review
This is a re-review scoped to 2 commits since the last automated review:
24205302a— refactor: drop build from ci-docs, let Vercel own the next build7e39baaf5— refactor: fold docs lint+typecheck back into main CI, delete ci-docs.yml
What changed: The separate ci-docs.yml workflow approach was abandoned. Instead:
- The 97-line
ci-docs.ymlwas deleted entirely - agents-docs lint+typecheck were folded back into main CI as a separate step (lines 115-120)
- The Next.js build remains excluded from CI — Vercel preview deployments handle it
Verification: ✅ This is a clean simplification. The original problem (OOM from the heavy Next.js build) is still solved by excluding @inkeep/agents-docs from the main turbo check. Lint and typecheck are lightweight operations that won't cause memory pressure.
🔴❗ Critical (0) ❗🔴
None.
🟠⚠️ Major (0) 🟠⚠️
None.
🟡 Minor (0) 🟡
None.
💭 Consider (1) 💭
Inline Comments:
- 💭 Consider:
ci.yml:115-120MissingNODE_OPTIONSheap limit for defensive CI hygiene
🕐 Pending Recommendations (0)
The prior inline comment on ci-docs.yml:6-10 about self-referential path triggers is now moot — that workflow file was deleted in this delta. No action needed.
✅ APPROVE
Summary: This delta is a sensible simplification of the CI approach. The original OOM issue is addressed (heavy Next.js build excluded, Vercel handles it), and lint+typecheck are now run in the main workflow where they're easier to maintain. The one "Consider" item (adding NODE_OPTIONS for defensive consistency) is optional — lint/typecheck are unlikely to hit memory limits. Clean work! 🚀
Discarded (0)
No findings discarded.
Reviewers (1)
| Reviewer | Returned | Main Findings | Consider | While You're Here | Inline Comments | Pending Recs | Discarded |
|---|---|---|---|---|---|---|---|
pr-review-devops |
1 | 0 | 0 | 0 | 1 | 0 | 0 |
| Total | 1 | 0 | 0 | 0 | 1 | 0 | 0 |
| # Lint and typecheck agents-docs separately (build excluded above to avoid OOM) | ||
| - name: Lint and typecheck agents-docs | ||
| run: | | ||
| pnpm exec turbo run lint typecheck --filter=@inkeep/agents-docs | ||
| env: | ||
| CI: true |
There was a problem hiding this comment.
💭 Consider: Missing NODE_OPTIONS heap limit
Issue: This step doesn't inherit NODE_OPTIONS from the previous step's env block. The main CI check sets --max-old-space-size=4096, but each GitHub Actions step has an isolated environment.
Why: While lint and typecheck are significantly lighter than the Next.js build that caused the original OOM issues, adding explicit heap limits provides defensive CI hygiene and makes resource expectations clear. Memory-related CI failures (SIGKILL/exit 137) are notoriously hard to debug when they do occur.
Fix: Consider adding NODE_OPTIONS for consistency:
env:
CI: true
NODE_OPTIONS: --max-old-space-size=4096Refs:
1 participant
Summary
@inkeep/agents-docsfrom main CIturbo checkto prevent OOM kills (exit code 137) when turbo cache misses cluster on the 16GB runnerci-docs.yml— a dedicated workflow that builds/lints/typechecks agents-docs in isolation onubuntu-latestwith an 8GB heapWhy
The main CI runs turbo with
concurrency: 15. When cache misses cluster (common on feature branches), 9+ Node.js processes launch simultaneously — each with a 4GB heap limit — and the Linux OOM killer sends SIGKILL. The agents-docs Next.js 16 build (335 static pages, 3.7min compile) is the heaviest task and a primary OOM contributor.agents-docs is a pure leaf node: nothing depends on it, it has no tests, and it's deployed separately via Vercel. Turbo's
--filter=@inkeep/agents-docswith^buildautomatically builds transitive deps (agents-core, agents-cli) first.ci-docs.yml triggers
main/ PRs touching:agents-docs/**,packages/agents-core/src/**,agents-cli/src/**,agents-api/__snapshots__/openapi.jsonTest plan
Manual QA scenarios verified locally via turbo dry-runs and on CI.
yaml.parse(). · Why not a test: CI infra config, not app codeturbo check --filter='!agents-cookbook-templates' --filter='!@inkeep/agents-docs'shows 66 tasks across 11 packages with 0 agents-docs references (was 72 tasks / 33 agents-docs refs before). · Why not a test: CI command behaviorturbo run build lint typecheck --filter=@inkeep/agents-docscorrectly includes: agents-core#build, agents-sdk#build, agents-cli#build (transitive deps), plus agents-docs#build/lint/typecheck. 10 tasks total. · Why not a test: turbo dependency resolutionagents-docs/**(direct),packages/agents-core/src/**(model constants import),agents-cli/src/**(type introspection import),agents-api/__snapshots__/openapi.json(API docs generation). · Why not a test: file path existence checkpackages/agents-cli/src/**but agents-cli lives at repo root (agents-cli/), not underpackages/. Fixed in commit 4576dad. · Why not a test: directory structure validationturbonot on CI PATH — Original usedturbo check ...directly; old CI usedpnpm checkwhich resolved turbo via package scripts. Fixed topnpm exec turbo check ...in commit ec3e8ad. · Why not a test: CI runner PATH config.github/workflows/which won't trigger ci-docs path filter. Needs a follow-up PR touching agents-docs files, or manualworkflow_dispatch. · Skipped: requires GHA path-filter evaluation on a different PR🤖 Generated with Claude Code