Workflows and runs

Where workflow files are read from, what starts a run, where it executes, and the statuses it goes through.

Last updated 18 November 2026View as Markdown

Workflow files

Folder Format Files read
.dcloud/workflows/, .ews/workflows/ Native (Workflow syntax) .yml, .yaml and .json
.github/workflows/ GitHub Actions .yml and .yaml, directly in the folder

When .dcloud/workflows/ and .ews/workflows/ hold a file of the same name, the one in .dcloud/workflows/ is read. A workflow is read at the commit the event names, so a change to a workflow takes effect on the commit that makes it. Three exceptions: a manual start reads the file at the tip of the ref you name, a required check reads the protected branch's copy (see Required checks), and a re-run repeats the file its original run used.

A file that does not parse never blocks a push; it starts no run. Check a file before you commit it (see Add a workflow).

What starts a run

  • A push of a branch or tag that the file's push trigger matches. Merging a pull request, committing in the console, creating a branch and updating a pull request's branch start what the same push would. An annotated tag is resolved to its commit first. A push made with a running job's own token starts no run, so a job that pushes a tag or a version bump does not start itself again.
  • A pull request whose target branch the pull_request trigger matches, built from the pull request's commit.
  • A merge queue build (merge_group).
  • A manual start of a file that allows it (see Start a workflow by hand).
  • In GitHub-syntax files also schedule, release and workflow_run (see Run GitHub Actions workflows).
  • A re-run of an earlier run (see Cancel or re-run a run).

In the native format, cancelInProgress: true cancels the queued and running runs of the same workflow name on the same ref when a new one starts, with "Superseded by run #…".

Where a run executes

The jobs ask for The run executes on
Linux only (native linux, GitHub ubuntu-*) One platform machine created for the run and deleted after it; its jobs share it
Labels a runner pool carries (GitHub syntax) The pool's machines, one job per machine
macos (native) One of your runners, which takes the whole run; it stays queued until one does
self-hosted or your runners' labels (GitHub) Your runners, which take the run's jobs one by one

A native run that mixes a linux and a macos job can only be taken by one runner carrying both labels, and a Mac cannot carry linux: put the macOS jobs in a workflow file of their own. See Runners and runner groups.

Statuses

Status Meaning
queued Waiting: for a free slot under the organization's ceiling on concurrent runs, or for a runner
provisioning The machine is being prepared
running Jobs are executing
succeeded Every job finished successfully
failed A job failed, or the run could not be planned or started
cancelled Cancelled by a person, or superseded by a newer run
timed_out The run passed its time limit

A queued run says why it waits (see Watch a run). A run on a platform machine or a Deutsche Cloud agent may last two hours. A run whose jobs go to GitHub's runner, yours or a runner pool's, may last 6 hours in a trial organization and 72 hours otherwise.

Did this page help you?