# Start a workflow by hand

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

The file must accept a manual start: a GitHub-syntax file under `.github/workflows/` with
`on: workflow_dispatch`, or a native file with a `manual` trigger under `on:`. The file is read at
the tip of the ref
you name, so what runs is what that branch or tag holds now.

Replace repo-id with the repository's id.

## Prerequisites

- `ci:StartWorkflow` on the repository (`rn:ews::<organization id>:ci:repository/<repository id>`).
- The run is started as you: the secrets its jobs get are checked against your
  `secrets:GetSecretValue` (see [Give a job a secret](give-a-job-a-secret.md)).

## Start the workflow

**Console:** not available. The console has no button to start a workflow by hand.

**CLI**
```sh
dcloud ci dispatch start repo-id --path .github/workflows/release.yml \
  --ref main --inputs channel=beta
```

**API**
```http
POST /ci/api/repositories/repo-id/workflows/dispatch
{ "path": ".github/workflows/release.yml", "ref": "main", "inputs": { "channel": "beta" } }
```

`ref` is a branch or a tag, by name or as a full ref (`refs/tags/v1.2.0`); a name that is no branch
is tried as a tag. Without `ref`, the default branch is used. Inputs you leave out take the defaults
the workflow declares.

## Result

`201` with `{ runId, workflowName, path }`; the run is queued with the trigger `manual`.

For a GitHub-syntax file, inputs are checked against its `workflow_dispatch` inputs before the run
exists:

- `400` "Unexpected inputs provided: …"
- `400` "Required input 'channel' not provided"
- `400` "Input 'dry-run' must be true or false", "… must be a number", "… must be one of: …",
  "… is not a valid environment name"

Other refusals:

- `400` "Invalid ref"; `404` "No such branch or tag: …".
- `404` ".github/workflows/release.yml is not a workflow file at main".
- `400` "Workflow is invalid: …" when the file does not parse.
- `409` "… did not start: … It needs `on: workflow_dispatch` (or `on.manual` in our format)" when
  the file does not accept a manual start.

## Related

- [Workflows and runs](workflows-and-runs.md)
- [Cancel or re-run a run](cancel-or-rerun-a-run.md)
- `ci.dispatch.start` · `dcloud ci dispatch start`
