docs: add workflows.mdx explaining the workflow engine - #998
Conversation
Adds comprehensive documentation for workflows covering: - Input types (string, number, boolean, object, array/selector) - How to wire job agents with CEL selectors - Go template syntax for passing inputs into job agent config - Full end-to-end examples (database migration, multi-agent restart) - Terraform provider resource examples - API reference and internal execution flow Co-authored-by: Aditya Choudhari <adityachoudhari26@users.noreply.github.com>
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 55 minutes and 15 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
✨ Finishing Touches🧪 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 |
|
|
There was a problem hiding this comment.
Pull request overview
Adds a new documentation page describing Ctrlplane’s workflow engine and wires it into the docs navigation so users can discover how to define workflows, run them, and integrate job agents.
Changes:
- Added
docs/workflows.mdxcovering workflow concepts, inputs/defaulting, agent selectors, examples, and API/Terraform usage. - Updated
docs/docs.jsonto include the new Workflows page in the docs sidebar.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.
| File | Description |
|---|---|
| docs/workflows.mdx | New end-to-end documentation for the workflow engine (inputs, selectors, examples, Terraform/API reference). |
| docs/docs.json | Adds workflows to the “Deployment” docs group navigation. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| **Selector array** — dynamically resolved from your inventory using a CEL expression. Instead of the caller listing items, Ctrlplane queries entities matching the selector: | ||
|
|
||
| ```json | ||
| { | ||
| "key": "targets", | ||
| "type": "array", | ||
| "selector": { | ||
| "entityType": "resource", | ||
| "default": "resource.metadata['environment'] == 'staging'" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| `entityType` can be `resource`, `environment`, or `deployment`. The `default` is a CEL expression used when the caller does not override the selector. | ||
|
|
There was a problem hiding this comment.
The doc describes a “Selector array” input that resolves items dynamically from inventory via selector.entityType/default, but the current workspace-engine workflow run implementation does not recognize/resolve selector array inputs (array inputs are ignored during input resolution, and the engine OAPI types only include a manual array variant). This section will mislead users unless selector arrays are implemented end-to-end; consider removing it or clearly marking it as not yet supported.
| Both `config` values and the `selector` field support **Go `text/template`** syntax. Templates are rendered before dispatch using the same dispatch context: | ||
|
|
||
| | Variable | Description | | ||
| | --- | --- | | ||
| | `{{.inputs.<key>}}` | Resolved input values | | ||
| | `{{.workflow}}` | The workflow definition | | ||
| | `{{.jobAgentConfig}}` | This agent's rendered config (available in nested templates) | |
There was a problem hiding this comment.
This section states that both config values and the agent selector support Go text/template and are rendered before dispatch. In the current implementation, workflow job-agent selector is evaluated as CEL (no template-rendering step), and most job-agent config fields are consumed as raw values (only specific agents template specific fields like Terraform Cloud/Argo templates). Please narrow this claim to the fields/agents that actually template, and avoid implying that selectors are templated.
| Both `config` values and the `selector` field support **Go `text/template`** syntax. Templates are rendered before dispatch using the same dispatch context: | |
| | Variable | Description | | |
| | --- | --- | | |
| | `{{.inputs.<key>}}` | Resolved input values | | |
| | `{{.workflow}}` | The workflow definition | | |
| | `{{.jobAgentConfig}}` | This agent's rendered config (available in nested templates) | | |
| Some job agents support **Go `text/template`** syntax in specific `config` fields. When supported by an agent, those fields are rendered before dispatch using the dispatch context below. The `selector` field does **not** use Go templates; it is evaluated as a CEL expression. | |
| | Variable | Description | | |
| | --- | --- | | |
| | `{{.inputs.<key>}}` | Resolved input values | | |
| | `{{.workflow}}` | The workflow definition | | |
| | `{{.jobAgentConfig}}` | This agent's rendered config (available in nested templates where supported) | |
| "installationId": "12345678", | ||
| "owner": "my-org", | ||
| "repo": "my-repo", | ||
| "workflowId": "deploy.yml" |
There was a problem hiding this comment.
The GitHub job-agent config example uses string values for installationId and workflowId (and uses a filename for workflowId). The GitHub job agent expects numeric installationId and a numeric GitHub workflow ID (not a YAML filename). Update the examples to use JSON numbers and a numeric workflow ID to match the integration docs and the dispatcher’s config parsing.
| "installationId": "12345678", | |
| "owner": "my-org", | |
| "repo": "my-repo", | |
| "workflowId": "deploy.yml" | |
| "installationId": 12345678, | |
| "owner": "my-org", | |
| "repo": "my-repo", | |
| "workflowId": 987654321 |
| "config": { | ||
| "installationId": "12345678", | ||
| "owner": "my-org", | ||
| "repo": "{{.inputs.repo}}", | ||
| "workflowId": "workflow-dispatch.yml", | ||
| "ref": "{{.inputs.branch}}" | ||
| }, | ||
| "selector": "true" |
There was a problem hiding this comment.
This GitHub Actions example templates repo/ref inside the workflow’s job-agent config (e.g., "repo": "{{.inputs.repo}}"). The workflow engine does not currently render Go templates across arbitrary job-agent config fields prior to dispatch, so these literal template strings would be passed through to the dispatcher. Consider removing templating from this config example (or documenting/implementing the exact supported templating behavior per agent/field).
| input { | ||
| key = "dry_run" | ||
| type = "boolean" | ||
| default = "true" |
There was a problem hiding this comment.
In the Terraform example, default = "true" is a string literal, but the input type is boolean. This should be a boolean (default = true) to avoid type errors when applying the config.
| default = "true" | |
| default = true |
| name = "migration-runner" | ||
| ref = ctrlplane_job_agent.github.id | ||
| selector = "true" | ||
|
|
||
| config = { | ||
| installationId = var.github_installation_id | ||
| owner = "my-org" | ||
| repo = "my-app" | ||
| workflowId = "migrate.yml" | ||
| ref = "main" |
There was a problem hiding this comment.
The Terraform snippets use a different shape/naming style than other Terraform examples in this docs set (e.g., job_agent { ref = ... selector = ... config = { installationId = ..., workflowId = ... } } vs existing job_agent { id = ... github { workflow_id = ... } } patterns). If the workflow Terraform resource follows the same provider conventions as deployments, this example will not work as written—please align the block/field names with the provider schema used elsewhere in the docs, or explicitly call out that workflows use a different HCL schema.
| name = "migration-runner" | |
| ref = ctrlplane_job_agent.github.id | |
| selector = "true" | |
| config = { | |
| installationId = var.github_installation_id | |
| owner = "my-org" | |
| repo = "my-app" | |
| workflowId = "migrate.yml" | |
| ref = "main" | |
| name = "migration-runner" | |
| id = ctrlplane_job_agent.github.id | |
| github { | |
| installation_id = var.github_installation_id | |
| owner = "my-org" | |
| repo = "my-app" | |
| workflow_id = "migrate.yml" | |
| ref = "main" |
| | Method | Endpoint | Description | | ||
| | --- | --- | --- | | ||
| | `GET` | `/v1/workspaces/{workspaceId}/workflows` | List all workflows | | ||
| | `POST` | `/v1/workspaces/{workspaceId}/workflows` | Create a workflow | | ||
| | `GET` | `/v1/workspaces/{workspaceId}/workflows/{workflowId}` | Get a workflow | | ||
| | `PUT` | `/v1/workspaces/{workspaceId}/workflows/{workflowId}` | Update a workflow | | ||
| | `DELETE` | `/v1/workspaces/{workspaceId}/workflows/{workflowId}` | Delete a workflow | | ||
| | `POST` | `/v1/workspaces/{workspaceId}/workflows/{workflowId}/runs` | Trigger a workflow run | | ||
|
|
There was a problem hiding this comment.
The API Reference table lists endpoints under /v1/..., but earlier examples in this doc (and elsewhere in the docs) use /api/v1/.... Unless both are valid base paths, this inconsistency will confuse readers—consider standardizing on the same prefix throughout this page.
Adds comprehensive documentation for the Ctrlplane workflow engine, covering input types and defaults, job agent wiring with CEL selectors, Go template syntax for passing inputs to agents, full end-to-end examples, and Terraform provider usage.
Closes #995
Generated with Claude Code