# Workflows and runs

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

## Workflow files

| Folder                                  | Format                                      | Files read                                 |
| --------------------------------------- | ------------------------------------------- | ------------------------------------------ |
| `.dcloud/workflows/`, `.ews/workflows/` | Native ([Workflow syntax](/docs/workflows)) | `.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](required-checks.md)), 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](add-a-workflow.md)).

## 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](start-a-workflow-by-hand.md)).
- In GitHub-syntax files also `schedule`, `release` and `workflow_run` (see
  [Run GitHub Actions workflows](run-github-actions-workflows.md)).
- **A re-run** of an earlier run (see [Cancel or re-run a run](cancel-or-rerun-a-run.md)).

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](runners-and-groups.md).

## 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](watch-a-run.md)). 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.

## Related

- [Workflow syntax](/docs/workflows)
- [Runners and runner groups](runners-and-groups.md)
- [What runs on your machines](what-runs-on-your-machines.md)
