docs: improve bulk actions docs#4211
Conversation
|
WalkthroughThis PR adds a new bulk actions API surface (list, create, retrieve, abort under /api/v1/bulk-actions) to the OpenAPI spec, including new parameters and schemas for filters, requests, and responses. Documentation is restructured: the legacy docs/management/runs/bulk-actions.mdx page is removed, a new docs/bulk-actions.mdx guide covers dashboard and SDK usage (replay, cancel, retrieve, poll, abort, list), new per-endpoint management reference pages are added, navigation and redirects are updated, and a cross-reference is added in the errors-retrying documentation. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI
Review profile: CHILL
Plan: Pro
Run ID: 3aa03664-a75c-4056-aaac-f0168ad38dbf
📒 Files selected for processing (9)
docs/bulk-actions.mdxdocs/docs.jsondocs/errors-retrying.mdxdocs/management/bulk-actions/abort.mdxdocs/management/bulk-actions/create.mdxdocs/management/bulk-actions/list.mdxdocs/management/bulk-actions/retrieve.mdxdocs/management/runs/bulk-actions.mdxdocs/v3-openapi.yaml
💤 Files with no reviewable changes (1)
- docs/management/runs/bulk-actions.mdx
📜 Review details
⏰ Context from checks skipped due to timeout. (2)
- GitHub Check: code-quality / code-quality
- GitHub Check: Analyze (javascript-typescript)
🧰 Additional context used
📓 Path-based instructions (3)
docs/**/*.mdx
📄 CodeRabbit inference engine (docs/CLAUDE.md)
docs/**/*.mdx: MDX documentation pages must include frontmatter with title (required), description (required), and sidebarTitle (optional) in YAML format
Use Mintlify components for structured content: , , , , , , /, /
Always import from@trigger.dev/sdkin code examples (never from@trigger.dev/sdk/v3)
Code examples must be complete and runnable where possible
Use language tags in code fences:typescript,bash,json
Files:
docs/management/bulk-actions/abort.mdxdocs/management/bulk-actions/retrieve.mdxdocs/management/bulk-actions/list.mdxdocs/management/bulk-actions/create.mdxdocs/errors-retrying.mdxdocs/bulk-actions.mdx
docs/**/docs.json
📄 CodeRabbit inference engine (docs/CLAUDE.md)
docs/**/docs.json: Main documentation config must be defined indocs.jsonwhich includes navigation structure, theme, and metadata
Navigation structure indocs.jsonshould be organized usingnavigation.dropdownswith groups and pages
Files:
docs/docs.json
**/{Dockerfile*,*.{yml,yaml}}
📄 CodeRabbit inference engine (AGENTS.md)
When updating Docker image references, always use multiplatform/index digests rather than architecture-specific digests.
Files:
docs/v3-openapi.yaml
🧠 Learnings (3)
📚 Learning: 2026-03-10T12:44:14.176Z
Learnt from: nicktrn
Repo: triggerdotdev/trigger.dev PR: 3200
File: docs/config/config-file.mdx:353-368
Timestamp: 2026-03-10T12:44:14.176Z
Learning: In the trigger.dev repo, docs PRs are often companions to implementation PRs. When reviewing docs PRs (MDX files under docs/), check the PR description for any companion/related PR references and verify that the documented features exist in those companion PRs before flagging missing implementations. This ensures docs stay in sync with code changes across related PRs.
Applied to files:
docs/management/bulk-actions/abort.mdxdocs/management/bulk-actions/retrieve.mdxdocs/management/bulk-actions/list.mdxdocs/management/bulk-actions/create.mdxdocs/errors-retrying.mdxdocs/bulk-actions.mdx
📚 Learning: 2026-04-30T20:30:29.458Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3226
File: docs/ai-chat/quick-start.mdx:13-13
Timestamp: 2026-04-30T20:30:29.458Z
Learning: In this repo’s documentation MDX files (`docs/**/*.mdx`), use `ts` and `tsx` (not `typescript`) as the code-fence language tags for TypeScript/TSX snippets. Do not flag `ts`/`tsx` code-fence language tags as incorrect in any docs MDX file, since this is the site-wide Mintlify-compatible convention.
Applied to files:
docs/management/bulk-actions/abort.mdxdocs/management/bulk-actions/retrieve.mdxdocs/management/bulk-actions/list.mdxdocs/management/bulk-actions/create.mdxdocs/errors-retrying.mdxdocs/bulk-actions.mdx
📚 Learning: 2026-06-14T17:36:56.078Z
Learnt from: ericallam
Repo: triggerdotdev/trigger.dev PR: 3942
File: docs/management/sessions/create.mdx:1-4
Timestamp: 2026-06-14T17:36:56.078Z
Learning: In trigger.dev docs, MDX pages under `docs/management/` that include an `openapi:` key in their frontmatter are intentional OpenAPI-driven reference stubs (typically `title` + `openapi` only). The page description is rendered from the referenced OpenAPI operation, so do not flag missing `description` frontmatter on these pages.
Applied to files:
docs/management/bulk-actions/abort.mdxdocs/management/bulk-actions/retrieve.mdxdocs/management/bulk-actions/list.mdxdocs/management/bulk-actions/create.mdx
🔇 Additional comments (16)
docs/bulk-actions.mdx (6)
3-12: LGTM!
25-54: LGTM!
55-97: LGTM!
98-127: LGTM!
196-227: 📐 Maintainability & Code QualityNo change needed for the frontmatter title
The frontmatter already includestitle: "Bulk actions".> Likely an incorrect or invalid review comment.
128-195: 🗄️ Data Integrity & IntegrationNo issue here
BulkActionObjectalready usesCANCEL/REPLAY,PENDING/COMPLETED/ABORTED, andcounts.total/success/failure.> Likely an incorrect or invalid review comment.docs/docs.json (2)
350-358: LGTM!
762-769: LGTM!docs/errors-retrying.mdx (1)
380-383: LGTM!docs/v3-openapi.yaml (3)
1702-1728: LGTM!Also applies to: 1810-1877, 3966-3995, 4708-4815, 4928-4962
1729-1740: 🎯 Functional CorrectnessNo change needed:
runs.bulk.*matches the public SDK surface.> Likely an incorrect or invalid review comment.
4834-4837: 🗄️ Data Integrity & IntegrationNo docs change needed. The request
actionis lowercase, while bulk-action responsetypeis uppercase by design; the OpenAPI matches the server schema.> Likely an incorrect or invalid review comment.docs/management/bulk-actions/create.mdx (1)
1-4: LGTM! Matches thecreate_bulk_action_v1operation added indocs/v3-openapi.yaml.
Based on learnings, MDX pages underdocs/management/with anopenapi:key are intentional OpenAPI-driven reference stubs and don't require adescriptionfield.docs/management/bulk-actions/list.mdx (1)
1-4: LGTM! Matches thelist_bulk_actions_v1operation added indocs/v3-openapi.yaml.
Based on learnings, MDX pages underdocs/management/with anopenapi:key are intentional OpenAPI-driven reference stubs and don't require adescriptionfield.docs/management/bulk-actions/retrieve.mdx (1)
1-4: LGTM! Matches theretrieve_bulk_action_v1operation added indocs/v3-openapi.yaml.
Based on learnings, MDX pages underdocs/management/with anopenapi:key are intentional OpenAPI-driven reference stubs and don't require adescriptionfield.docs/management/bulk-actions/abort.mdx (1)
1-4: LGTM! Matches theabort_bulk_action_v1operation added indocs/v3-openapi.yaml.
Based on learnings, MDX pages underdocs/management/with anopenapi:key are intentional OpenAPI-driven reference stubs and don't require adescriptionfield.
| runIds: | ||
| type: array | ||
| minItems: 1 | ||
| items: | ||
| type: string |
There was a problem hiding this comment.
🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win
Bound runIds array size.
runIds has minItems: 1 but no upper bound, unlike other array fields in this spec (e.g. batch trigger items has maxItems: 1000, RunTags has maxItems: 10). An unbounded list of run IDs in a single bulk action request could allow oversized payloads/requests that strain backend processing.
🛡️ Proposed fix to bound runIds
runIds:
type: array
minItems: 1
+ maxItems: 1000
items:
type: stringAlso applies to: 4863-4867
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| BulkActionFilter: | ||
| type: object | ||
| description: Selects runs using the same filter shape as `runs.list()`, excluding pagination fields. Provide at least one property. | ||
| minProperties: 1 | ||
| properties: | ||
| status: | ||
| oneOf: | ||
| - type: string | ||
| enum: | ||
| - PENDING_VERSION | ||
| - QUEUED | ||
| - EXECUTING | ||
| - REATTEMPTING | ||
| - FROZEN | ||
| - COMPLETED | ||
| - CANCELED | ||
| - FAILED | ||
| - CRASHED | ||
| - INTERRUPTED | ||
| - SYSTEM_FAILURE | ||
| - type: array | ||
| items: | ||
| type: string | ||
| enum: | ||
| - PENDING_VERSION | ||
| - QUEUED | ||
| - EXECUTING | ||
| - REATTEMPTING | ||
| - FROZEN | ||
| - COMPLETED | ||
| - CANCELED | ||
| - FAILED | ||
| - CRASHED | ||
| - INTERRUPTED | ||
| - SYSTEM_FAILURE | ||
| taskIdentifier: | ||
| oneOf: | ||
| - type: string | ||
| - type: array | ||
| items: | ||
| type: string | ||
| description: The identifier of the task that was run. | ||
| version: | ||
| oneOf: | ||
| - type: string | ||
| - type: array | ||
| items: | ||
| type: string | ||
| description: The worker version that executed the run. | ||
| from: | ||
| oneOf: | ||
| - type: string | ||
| format: date-time | ||
| - type: number | ||
| description: Start of the time range as an ISO date string or Unix timestamp in milliseconds. | ||
| to: | ||
| oneOf: | ||
| - type: string | ||
| format: date-time | ||
| - type: number | ||
| description: End of the time range as an ISO date string or Unix timestamp in milliseconds. | ||
| period: | ||
| type: string | ||
| description: Relative time period to select, such as `24h` or `30d`. | ||
| example: 24h | ||
| bulkAction: | ||
| type: string | ||
| description: Select runs that were processed by another bulk action. | ||
| example: bulk_1234 | ||
| tag: | ||
| oneOf: | ||
| - type: string | ||
| - type: array | ||
| items: | ||
| type: string | ||
| description: Select runs with one or more tags. | ||
| schedule: | ||
| type: string | ||
| description: Select runs created by a schedule. | ||
| example: sched_1234 | ||
| isTest: | ||
| type: boolean | ||
| description: Select test or non-test runs. | ||
| batch: | ||
| type: string | ||
| description: Select runs in a batch. | ||
| example: batch_1234 | ||
| queue: | ||
| oneOf: | ||
| - $ref: "#/components/schemas/QueueTypeName" | ||
| - type: array | ||
| items: | ||
| $ref: "#/components/schemas/QueueTypeName" | ||
| machine: | ||
| oneOf: | ||
| - type: string | ||
| - type: array | ||
| items: | ||
| type: string | ||
| description: Select runs by machine preset. | ||
| region: | ||
| oneOf: | ||
| - type: string | ||
| - type: array | ||
| items: | ||
| type: string | ||
| description: Select runs by region. |
There was a problem hiding this comment.
🔍 BulkActionFilter schema differs structurally from CommonRunsFilter despite docs claiming same shape
The docs at docs/bulk-actions.mdx:76 and docs/bulk-actions.mdx:83 state that filter accepts "the same filter shape as runs.list()". However, the OpenAPI BulkActionFilter schema (docs/v3-openapi.yaml:4708-4814) differs from CommonRunsFilter (docs/v3-openapi.yaml:4453-4540) in several ways:
- Time fields (
from,to,period) are flat top-level properties inBulkActionFilter, whereas inCommonRunsFilterthey are nested under acreatedAtobject. BulkActionFilterallows single string OR array viaoneOfforstatus,taskIdentifier,version, andtag, whileCommonRunsFilteronly accepts arrays.BulkActionFilterincludes additional fields not inCommonRunsFilter:batch,queue,machine,region.
This is likely intentional — the SDK probably normalizes between these shapes — but the documentation's claim of "same filter shape" could mislead users who try to pass the raw HTTP API filter from runs.list() directly to the bulk action endpoint. If the SDK handles the mapping, this is fine, but it's worth confirming that the SDK documentation matches the actual API contract.
Was this helpful? React with 👍 or 👎 to provide feedback.
2 participants
Todo