# Writing a Deutsche Cloud workflow file

You are writing a CI workflow file for **Deutsche Cloud**, a cloud platform with its own
continuous-integration service. Deutsche Cloud is not GitHub and not GitLab: it has its own
workflow format, described completely below. Everything in this document is
generated from the parser that will validate your file, so it is exactly what
the platform accepts — no more and no less.

Read this whole document before writing anything. Then produce **one workflow
file** and nothing else.

## Where the file goes

`.dcloud/workflows/<name>.yml` in the repository, e.g. `.dcloud/workflows/ci.yml`.
A repository set up earlier may keep its workflows in `.ews/workflows/`, which
is read the same way; add a file next to the ones it already has.
One workflow per file. YAML and JSON are both accepted and parse to the same
thing; write YAML unless asked otherwise. The file is validated when it is
pushed, and an invalid file is reported against the exact key rather than
failing halfway through a run.

## The model in one minute

- A workflow has a `name`, its triggers under `on:`, and a map of `jobs:`.
- A job runs its `steps:` in order, in one workspace, in one container image
  (or natively on a Mac runner).
- Jobs with no `needs:` between them run at the same time.
- **There is no checkout step.** The workspace already holds the repository at
  the commit that triggered the run.
- **There is no registry login step.** Credentials for the organization's own
  container registry are injected into the run.
- **There are no third-party actions.** A step is one of exactly five kinds:
  `run`, `build-image`, `push-image`, `cache`, `artifact`. Anything a marketplace action
  would have done is either built in (image builds, caching, artifacts) or is a
  shell command you write yourself.
- An unknown key anywhere is a **parse error**, not something quietly ignored.
  Never invent a key.

## Key reference

### Top level

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `name` | string, 1–200 characters | **yes** | — | The workflow’s name, shown against the commit and in the run list. |
| `on` | object | **yes** | — | The triggers. At least one of `push`, `pull_request`, `manual` is required. |
| `env` | map of string → string | no | — | Environment variables in scope for every job. Scalars become strings. |
| `cancelInProgress` | boolean | no | `false` | Supersede an older in-flight run of this workflow on the same ref. |
| `jobs` | map of string → object | **yes** | — | The jobs, keyed by name. Jobs with no `needs` between them run at once. |

### `on` — triggers

At least one trigger must be present. A trigger may be written with no value at
all (`push:`), which means "this event, with defaults".

#### `on.push`

Runs on a push. An empty value means every branch push.

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `branches` | list of string, each 1–200 characters | no | every branch | Branch patterns. `*` within a path segment, `**` across them. |
| `tags` | list of string, each 1–200 characters | no | no tag fires | Tag patterns. A `push` trigger with only `branches:` never fires for a tag, and one with only `tags:` never fires for a branch — keep the two in separate files. |
| `paths` | list of string, each not empty | no | every path | Only run when one of these paths changed. |

#### `on.pull_request`

Runs on a pull request, built from the source commit.

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `branches` | list of string, each 1–200 characters | no | every branch | Matched against the **target** branch of the pull request. |
| `paths` | list of string, each not empty | no | every path | Only run when one of these paths changed. |

#### `on.merge_group`



| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `branches` | list of string, each 1–200 characters | no | — |  |

#### `on.manual`

Parses and satisfies the "at least one trigger" rule, but nothing dispatches it today — only **Re-run** starts a run outside an event.

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `inputs` | map of string → object | no | — | Declared inputs. Each takes `description`, `required` and `default`. |

### `jobs.<name>`

Job names match `[A-Za-z0-9][A-Za-z0-9_-]*`.

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `name` | string, 1–200 characters | no | the job’s key | The label shown for this job in the console. |
| `image` | string, 1–300 characters | no | the platform base image (a Debian slim) | The container image the job’s steps run in. Not available on a `macos` job — there is no container engine on the Mac, and naming an image there is a parse error rather than a silent no-op. |
| `runs-on` | `linux` or `macos` | no | `linux` | `linux` is a machine the platform creates for the run and destroys afterwards. `macos` is one of the organization’s own registered runners, so it only works when the organization has one. |
| `needs` | list of string, each 1–100 characters, matches `^[A-Za-z0-9][A-Za-z0-9_-]*$` | no | — | Job names in this same workflow that must finish successfully first. A cycle, or a name no job defines, is a parse error. |
| `if` | string, at most 500 characters | no | `success()` | A condition on the whole job: `==` / `!=` against a literal. Status functions are not allowed here — only on a step. |
| `env` | map of string → string | no | — | Merged over the workflow’s `env` for this job. |
| `timeout` | integer, 1–21600 | no | — | Seconds before the whole job is killed. |
| `strategy` | object | no | — |  |
| `secrets` | list of string, each 1–200 characters | no | — | Names of organization secrets to expose to this job’s `run` steps, also readable as `${{ secrets.NAME }}`. The secret must additionally be granted to the `actions` consumer by an administrator; a sibling job that does not list the name does not get it. |
| `environment` | string, matches `^[a-z0-9][a-z0-9-]{0,62}$` | no | — |  |
| `steps` | list of step, at least one entry | **yes** | — | At least one step. They run in order in one workspace. |

### Keys every step accepts

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `name` | string, 1–200 characters | no | derived from the step | The label for this step in the run view. |
| `if` | string, at most 500 characters | no | `success()` | A condition. `success()`, `failure()`, `cancelled()` and `always()` are available here and nowhere else. |
| `env` | map of string → string | no | — | Merged over the job’s `env` for this step. |
| `workdir` | string, at most 500 characters | no | the workspace root | Relative to the workspace root. |
| `timeout` | integer, 1–21600 | no | — | Seconds before this step is killed. |
| `continueOnError` | boolean | no | `false` | The job carries on when this step fails. |

### The step kinds

A step is **exactly one** of the following, plus any of the common keys above.
Two kinds in one step, or a kind that is not listed, is a parse error.

#### `run`

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `run` | string, not empty | **yes** | — | A shell command. A multi-line string runs as a script with `set -e`, so the first failing line fails the step. |
| `shell` | `sh` or `bash` | no | `sh` | Which shell runs the script. |

#### `build-image`

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `dockerfile` | string, 1–500 characters | no | `Dockerfile` | Path to the Dockerfile, relative to the workspace. |
| `context` | string, at most 500 characters | no | the workspace | Build context directory. |
| `target` | string, at most 200 characters | no | the last stage | Which stage of a multi-stage build to stop at. |
| `buildArgs` | map of string → string | no | — | Build arguments. Scalars become strings. |
| `tags` | list of string, each 1–200 characters | no | the short commit sha | Tags to apply to the built image. |

#### `push-image`

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `repository` | string, 1–200 characters | **yes** | — | A repository in the organization’s own container registry, created private by the first push that names it. Registry credentials are injected into the run — there is no login step, and no registry host to write. |
| `tags` | list of string, each 1–200 characters | no | the short commit sha | Every tag pushed must also have been produced by a `build-image` step in the same job. |

#### `cache`

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `key` | string, 1–500 characters | **yes** | — | The exact cache key, usually built from a lockfile hash: `pnpm-${{ hash('pnpm-lock.yaml') }}`. |
| `restoreKeys` | list of string, each 1–500 characters | no | — | Prefixes to fall back to on a miss, most specific first. A prefix hit is re-saved under the exact key. |
| `paths` | list of string, at least one entry, each 1–500 characters | **yes** | — | Directories to restore at this step’s position and save after the job. A miss never fails the build. |

#### `artifact`

| Key | Type | Required | Default | What it does |
| --- | ---- | -------- | ------- | ------------ |
| `name` | string, 1–200 characters | **yes** | — | The name the artifact is downloaded under from the run page. |
| `paths` | list of string, at least one entry, each 1–500 characters | **yes** | — | Files or directories to upload. A failed upload fails the step. |
| `retentionDays` | integer, 1–90 | no | the organization’s setting | How long to keep it. |

## Expressions

`${{ … }}` is resolved by the control plane before the machine boots, so a
step receives literal strings. The set is closed — an unknown reference or
function is a parse error on the file.

| Reference | Value |
| --------- | ----- |
| `commit.sha` / `commit.short` | the full commit id / its first 8 characters |
| `commit.message` / `commit.author` | the commit subject / its author |
| `repo.name` / `repo.defaultBranch` | the repository's name / its default branch |
| `run.id` / `run.number` / `run.attempt` | the run's id / its number in this repository / always `1` |
| `ref` | `refs/heads/main`, `refs/tags/v1.2.3` |
| `branch` | `main`; empty on a tag run |
| `tag` | `v1.2.3`; empty on a branch run |
| `env.NAME` | an environment variable in scope at that point |
| `secrets.NAME` | only when the job lists `NAME` under `secrets:` |

| Function | Example |
| -------- | ------- |
| `join(a, b, …, separator)` | `join(repo.name, commit.short, '-')` |
| `lower(value)` / `upper(value)` | `lower(branch)` |
| `slice(value, start[, end])` | `slice(tag, 1)` → `1.2.3` from `v1.2.3` |
| `replace(value, from, to)` | `replace(branch, '/', '-')` |
| `hash('path')` | sha256 of that file at the run's commit; the path must be a literal |

Conditions: `success()`, `failure()`, `cancelled()` and `always()` are
available in a **step's** `if:` only. `==` and `!=` against a literal work in
a job's `if:` or a step's `if:`.

## Secrets

A job reads a secret only when **both** are true: the job lists the name under
`secrets:`, and an administrator has granted that secret to the `actions`
consumer in the Deutsche Cloud console. Secrets are never written into the workflow file.
Keep secret names exactly as they were in the source file — renaming them turns
a configuration step into a hunt.

## Not supported — say so rather than approximating

If the source file uses one of these, do not invent an equivalent. Leave the
work out and record it in a note comment at the top of the file (see the output
rules below).

- **Matrix / parallel builds.** Write one job per variant instead.
- **Service or sidecar containers** alongside a job. Run the dependency inside a
  step, or use a managed database from the platform and pass its connection
  string in as a secret.
- **Third-party actions / marketplace steps / GitLab `include`.** Their work has
  to become shell commands.
- **Reusable, composite or templated workflows.**
- **Manual dispatch with inputs.** `on: manual:` parses, but only **Re-run**
  starts a run outside an event.
- **Scheduled / cron triggers.**
- **Environments, approvals, deployment gates, concurrency groups** (other than
  `cancelInProgress`).
- **Masking secrets in log output.**
- **Multiple attempts per run** — `${{ run.attempt }}` is always `1`.

## GitHub Actions → Deutsche Cloud

| GitHub Actions | Deutsche Cloud |
| -------------- | --- |
| `name:` | `name:` — unchanged |
| `on: push:` / `on: pull_request:` | `on: push:` / `on: pull_request:` — same shape, and `branches:`/`tags:`/`paths:` carry over |
| `on: push: tags:` | `on: push: tags:` — but keep tag workflows in their own file; one `push` trigger does not fire for both a branch and a tag |
| `on: workflow_dispatch:` | `on: manual:` — parses, but nothing dispatches it yet; say so in a note |
| `on: schedule:` | not supported — say so in a note |
| `jobs.<id>.runs-on: ubuntu-latest` | `runs-on: linux` (the default — omit it) |
| `jobs.<id>.runs-on: macos-latest` | `runs-on: macos`, and drop any `image:` — a Mac job runs natively |
| `jobs.<id>.runs-on: windows-latest` | not supported — say so in a note |
| `jobs.<id>.container.image` | `image:` on the job |
| `jobs.<id>.needs` | `needs:` — unchanged |
| `jobs.<id>.if` / `steps[].if` | `if:` — rewrite the expression into `==`/`!=` or a status function; `github.*` context becomes `commit.*`, `branch`, `tag`, `repo.*` |
| `jobs.<id>.timeout-minutes: 30` | `timeout: 1800` — Deutsche Cloud counts **seconds** |
| `env:` at any level | `env:` at the same level |
| `steps[].uses: actions/checkout@v4` | **nothing** — delete the step, checkout is implicit |
| `steps[].uses: actions/setup-node@v4` | either an `image:` on the job (`node:22`) or a `run:` step that installs the toolchain |
| `steps[].uses: actions/setup-python`, `setup-go`, `setup-java`, … | same: pick an `image:`, or install in a `run:` step |
| `steps[].uses: actions/cache@v4` (`with: path/key/restore-keys`) | a `cache:` step (`paths`, `key`, `restoreKeys`) |
| `steps[].uses: actions/upload-artifact@v4` | an `artifact:` step (`name`, `paths`, `retentionDays`) |
| `steps[].uses: actions/download-artifact@v4` | not supported — say so in a note |
| `steps[].uses: docker/login-action` | **nothing** — delete it, registry credentials are injected |
| `steps[].uses: docker/build-push-action` | a `build-image:` step and, when `push: true`, a `push-image:` step after it |
| `steps[].uses: docker/setup-buildx-action`, `setup-qemu-action` | **nothing** — delete them |
| any other `uses:` | not supported — replace it with the `run:` commands it would have executed, and say so in a note |
| `steps[].run` (`shell:`, `working-directory:`) | `run:` (`shell:` — `sh` or `bash` only, `workdir:`) |
| `steps[].continue-on-error` | `continueOnError:` |
| `${{ secrets.X }}` | `${{ secrets.X }}`, and list `X` under the job's `secrets:` — keep the name identical |
| `${{ github.sha }}` / `github.ref_name` / `github.repository` | `${{ commit.sha }}` / `${{ branch }}` / `${{ repo.name }}` |
| `strategy.matrix` | not supported — write one job per variant |
| `services:` | not supported — run the dependency in a step, or use a managed database |
| `concurrency: cancel-in-progress: true` | `cancelInProgress: true` at the top level |
| `permissions:`, `environment:`, `defaults:`, `outputs:` | not supported — say so in a note |

## GitLab CI → Deutsche Cloud

| GitLab CI | Deutsche Cloud |
| --------- | --- |
| a top-level job key | an entry under `jobs:` with the same name (sanitised to `[A-Za-z0-9][A-Za-z0-9_-]*`) |
| `stages:` + `stage:` | `needs:` — every job in stage N gets `needs:` on the jobs of stage N−1 |
| `needs:` | `needs:` — unchanged |
| `image:` | `image:` on the job |
| `script:` | one `run:` step per line, or a single multi-line `run:` |
| `before_script:` | `run:` steps at the start of the same job — repeat them per job, there is no global default |
| `after_script:` | a final `run:` step with `if: always()` |
| `variables:` | `env:` at the matching level |
| `rules:` / `only:` / `except:` on branches | `on: push: branches:` / `on: pull_request:`, plus a job `if:` where a per-job condition is needed |
| `rules:` on `$CI_PIPELINE_SOURCE == "merge_request_event"` | `on: pull_request:` |
| `only: tags` / `rules: $CI_COMMIT_TAG` | `on: push: tags: ['*']` in a file of its own |
| `artifacts: paths:` | an `artifact:` step (`name`, `paths`) |
| `artifacts: expire_in:` | `retentionDays:` on the `artifact:` step — in **days** |
| `artifacts: reports:` | not supported — upload the file as a plain artifact and say so in a note |
| `cache: key/paths` | a `cache:` step (`key`, `paths`, `restoreKeys`) placed before the steps that use it |
| `services:` | not supported — run the dependency in a step, or use a managed database |
| `include:` / `extends:` / `!reference` | not supported — inline what they would have produced, and say so in a note |
| `parallel: matrix:` | not supported — write one job per variant |
| `timeout: 30m` | `timeout: 1800` — Deutsche Cloud counts **seconds** |
| `retry:`, `allow_failure: true` | `allow_failure` becomes `continueOnError: true`; `retry` is not supported |
| `when: always` / `when: on_failure` | `if: always()` / `if: failure()` on the step |
| `when: manual` | not supported — say so in a note |
| `environment:`, `resource_group:`, `dependencies:` | not supported — say so in a note |
| `docker build` + `docker push` in a `script:` | a `build-image:` step and a `push-image:` step; delete any `docker login` |
| `$CI_COMMIT_SHA` / `$CI_COMMIT_SHORT_SHA` | `${{ commit.sha }}` / `${{ commit.short }}` |
| `$CI_COMMIT_REF_NAME` / `$CI_COMMIT_TAG` | `${{ branch }}` / `${{ tag }}` |
| `$CI_PROJECT_NAME` | `${{ repo.name }}` |
| a masked CI/CD variable | `${{ secrets.NAME }}` plus `secrets: [NAME]` on the job — keep the name identical |

## Examples

### Test on every pull request

```yaml
name: Pull request checks
on:
  pull_request:
    branches: [main]

cancelInProgress: true

jobs:
  test:
    image: node:22
    steps:
      - cache:
          key: pnpm-${{ hash('pnpm-lock.yaml') }}
          restoreKeys: [pnpm-]
          paths: [node_modules]
      - run: corepack pnpm install --frozen-lockfile
      - name: Unit tests
        run: corepack pnpm test
      - name: Keep the coverage report
        if: always()
        artifact:
          name: coverage
          paths: [coverage]
```

### Build and push an image on the default branch

```yaml
name: Publish from main
on:
  push:
    branches: [main]

jobs:
  publish:
    image: node:22
    secrets: [NPM_TOKEN]
    steps:
      - run: corepack pnpm install --frozen-lockfile
      - run: corepack pnpm build
      - build-image:
          dockerfile: Dockerfile
          buildArgs:
            COMMIT: ${{ commit.short }}
          tags: ['${{ commit.short }}', latest]
      - push-image:
          repository: api
          tags: ['${{ commit.short }}', latest]
```

### A macOS job

```yaml
name: iOS build
on:
  push:
    branches: [main]

jobs:
  ios:
    runs-on: macos
    timeout: 3600
    steps:
      - run: xcodebuild -scheme App -destination 'generic/platform=iOS' build
      - artifact:
          name: app
          paths: [build/Release-iphoneos/App.app]
```

## Rules for the output

1. Output **only the workflow file**, in a single fenced ```yaml block. No
   prose before it, no explanation after it.
2. **Never invent a key.** Every key you write must appear in the reference
   above. If you are unsure a key exists, it does not.
3. When something in the source has **no Deutsche Cloud equivalent**, leave it out and say
   so in a comment line at the very top of the file, before `name:`, in the
   form `# note: <what was dropped, and what to do instead>` — one line per
   dropped thing. These lines are read back by the console and shown to the
   person as a to-do list, so write them for them, not for yourself.
4. Prefer `runs-on: linux` — omit `runs-on` entirely unless the source
   genuinely needs macOS.
5. Keep **secret names identical** to the source, and list every one you
   reference under that job's `secrets:`.
6. Delete checkout steps, registry login steps and buildx/QEMU setup steps —
   they have no Deutsche Cloud equivalent because the platform already does them.
7. Convert every duration to **seconds**.
8. Preserve the source's job names, step names and command lines wherever the
   format allows; a reviewer should be able to read the two files side by side.
