ci.dispatch.start

Run one workflow file now, at a branch or tag, with inputs

POST /ci/api/repositories/{repoId}/workflows/dispatchIAM ci:StartWorkflowChanges state

A `.github/workflows/` file needs `on: workflow_dispatch`; a `.dcloud/workflows/` file (or `.ews/workflows/`, the earlier name; `.dcloud` wins on a name clash) needs `on.manual`. The file is read at the tip of `ref` (default branch when absent); declared input defaults fill what is not passed. 201 with `{ runId, workflowName, path }`; 409 when the file does not accept a manual start.

Request syntax

POST /ci/api/repositories/{repoId}/workflows/dispatch
{
  "path": "string",
  "ref": "string",
  "inputs": "map of string"
}

Path parameters

  • repoIdRequired

    string

    Constraints: uuid

Request body

  • pathRequired

    string

    Workflow file, e.g. .github/workflows/ci.yml

    Constraints: 1-500 chars

  • refOptional

    string

    Branch or tag; the default branch when absent

    Constraints: 1-250 chars

  • inputsOptional

    map of string

    workflow_dispatch inputs, name → value

    Constraints: key=value

Response

201 with { runId, workflowName, path }; the run is queued. 400 for an invalid ref, inputs the workflow refuses (unknown, missing required, wrong type, not among a choice) or an invalid workflow file; 404 when the repository, the branch or tag, or a workflow at path is not there; 409 when the file does not accept a manual start.

A JSON response is wrapped as { "success": true, "data": … }; the CLI prints the whole body with --json.

Errors

  • 400The request does not pass the schema above. The body is { "error": …, "issues": […] }, one issue per field.
  • 401No credentials, or an access key that is unknown, revoked or expired.
  • 403The caller's policies do not allow ci:StartWorkflow on this resource. The body names the action and the resource, and the refusal is recorded in the audit log.
  • 404The resource does not exist in your organization.

Examples

The required parameters only, with example values. Replace id and the other placeholders with your own.

dcloud ci dispatch start repoId --path example

Generated from the API description, the same one the API checks requests against and the CLI is built from. MCP tool: dcloud_ci_dispatch_start.