Workflow syntax

Every key a workflow file accepts, and what it does.

What it is

A workflow is a file in .dcloud/workflows/ (or, in a repository set up before the rename, .ews/workflows/: both are read, and a file in .dcloud/workflows/ wins over one of the same name) in your repository, written as YAML or JSON — both parse to the same thing. It names its triggers and its jobs, and each job's steps run in a container on the machine the run gets. Workflows and their runs appear under CI in the console and under Git → Repositories → Actions.

This page lists every key a workflow file accepts. For how a run reaches the registry and what it is allowed to do, see CI/CD pipeline.

Already have a GitHub Actions or GitLab CI file?

A GitHub Actions file does not need translating at all: leave it in .github/workflows/ and it runs as it is — see GitHub Actions workflows.

For a GitLab CI file, or to move a GitHub workflow onto this format, you do not have to translate it by hand. The console converts one for you under CI → Workflows → Convert: paste the file, pick where it came from, and you get a Deutsche Cloud workflow that has already been through the parser, with a # note: line at the top for anything that has no equivalent here.

If you would rather do it in the AI session you already have open on the repository — where the model can also see your Dockerfile, your lockfile and the scripts a workflow has to call — take the same instructions the console uses from /docs/workflows/prompt.md and paste them in, then paste your old file after them. That document is generated from the parser itself, so it describes this format exactly, and it carries the full GitHub Actions and GitLab CI mapping tables.

Concepts

Term Meaning
Trigger An entry under on: — push, pull_request, merge_group or manual. At least one is required.
Job A named group of steps in one container image. Jobs with no needs between them run at the same time.
Step Exactly one of run, build-image, push-image, cache or artifact, plus the common keys.
Expression ${{ … }} — a fixed set of references and functions, resolved before the machine boots.
Condition An if: on a job or a step: success(), failure(), cancelled(), always(), or an == / != comparison.
Secret A name a job lists under secrets:, exported into that job's run steps. It must also be granted to actions.

How to

Write the smallest useful workflow

name: Build and test
on:
  push:
    branches: [main]

jobs:
  test:
    steps:
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

There is no checkout step: the workspace already holds your repository at the triggering commit.

Run on a push to a branch

name: Publish from main
on:
  push:
    branches: [main, 'release/*']
    paths: ['app/**', 'Dockerfile']

env:
  NODE_ENV: production

jobs:
  publish:
    image: node:22
    steps:
      - cache:
          key: pnpm-${{ hash('pnpm-lock.yaml') }}
          restoreKeys: [pnpm-]
          paths: [node_modules]
      - run: pnpm build
      - build-image:
          dockerfile: Dockerfile
          tags: ['${{ commit.short }}', latest]
      - push-image:
          repository: api
          tags: ['${{ commit.short }}', latest]

Run on a pull request

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

cancelInProgress: true

jobs:
  test:
    image: node:22
    steps:
      - run: pnpm install --frozen-lockfile
      - run: pnpm test
      - artifact:
          name: coverage
          paths: [coverage]
          if: always()

  image:
    name: Build the image
    needs: [test]
    steps:
      - build-image: { dockerfile: Dockerfile, tags: ['pr-${{ commit.short }}'] }

branches: on a pull request matches the target branch. The run is built from the source commit — the tip of the branch being proposed.

Run on a version tag

name: Publish a release
on:
  push:
    tags: ['v*']

jobs:
  publish:
    secrets: [NPM_TOKEN]
    steps:
      - run: npm publish
      - build-image:
          dockerfile: Dockerfile
          buildArgs: { VERSION: '${{ slice(tag, 1) }}' }
          tags: ['${{ slice(tag, 1) }}']
      - push-image:
          repository: api
          tags: ['${{ slice(tag, 1) }}']

slice(tag, 1) drops the leading v, so v1.2.3 publishes :1.2.3. A push trigger declaring only branches: never fires for a tag, and one declaring only tags: never fires for a branch — keep the two in separate files.

Use a secret

List the name on the job, and have an administrator grant that secret to the actions consumer under Secrets → the secret → Consumers. Each listed name is exported into that job's run steps, and is available as ${{ secrets.NAME }} in a value, a build arg, a tag or an if:.

To take a secret from an environment, give the job environment: with the environment's slug. The job then gets that environment's secret of each listed name, and the shared one where the environment has none. It never gets another environment's. An unknown slug fails the run before any job starts.

jobs:
  deploy:
    environment: prod
    secrets: [STRIPE_KEY]
    steps:
      - run: ./deploy.sh

Reference

Top level

Key Type Default Constraints
name string required 1–200 characters; identifies the check on a commit
on triggers required at least one of push, pull_request, merge_group, manual
env map of string none in scope for every job; scalars are coerced to strings
cancelInProgress boolean false supersedes older in-flight runs of this workflow on this ref
jobs map of name → job required names match [A-Za-z0-9][A-Za-z0-9_-]*, 1–100 characters

on

Key Type Default Constraints
push object or empty absent empty means "every branch push, defaults apply"
push.branches list of patterns every branch 1–200 characters each
push.tags list of patterns no tag fires a tag push needs this key present
push.paths list of patterns every path matched against the commit's changed paths
pull_request object or empty absent empty means "every pull request"
pull_request.branches list of patterns every branch matched against the target branch
pull_request.paths list of patterns every path matched against the changed paths
merge_group object or empty absent a merge queue build (see /docs/git)
merge_group.branches list of patterns every branch matched against the base branch the queue lands on
manual object or empty absent parses; nothing dispatches it
manual.inputs map none each entry takes description (≤200), required, default

* matches within a path segment, ** across segments, so release/* matches release/1.2 but not release/1/2. YAML is parsed at 1.2, so on stays the string on and no stays no.

jobs.<name>

Key Type Default Constraints
name string the job's key 1–200 characters; the label in the console
image string docker.io/library/debian:bookworm-slim 1–300 characters; not on a macos job
runs-on linux, macos linux macos runs on your own Mac (see macOS runners)
strategy object none a matrix of legs, see below
needs list of names none job names in this workflow; a cycle is an error
if string success() ≤500 characters; no status functions here
env map of string none merged over the workflow's env
timeout integer seconds none 1–21600
secrets list of names none ≤200 characters each; must be granted to actions
environment string none (shared secrets only) an environment slug under Secrets → Environments
steps list of steps required at least one

jobs.<name>.strategy

Key Type Default Constraints
matrix.<key> list of strings or numbers — one dimension; keys are letters, digits, _ and -
matrix.include list of maps none extends matching combinations, or adds one of its own (GitHub's rules)
matrix.exclude list of maps none removes the combinations it matches
fail-fast boolean true the first failed leg cancels legs that have not started
max-parallel integer all 1–256 legs at once

At most 256 combinations. Each one is a job of its own, named name (value, value); ${{ matrix.<key> }} reads its value, and needs: on the job waits for every leg. Only fixed lists: a matrix from an expression is an error.

Keys every step accepts

Key Type Default Constraints
name string derived 1–200 characters
if string success() ≤500 characters; status functions allowed here only
env map of string none merged over the job's env
workdir string workspace root ≤500 characters, relative to the workspace
timeout integer seconds none 1–21600
continueOnError boolean false the job carries on when this step fails

An unrecognised key on a step is an error, not something dropped — image: belongs on the job.

run

Key Type Default Constraints
run string — at least 1 character; multi-line runs with set -e
shell enum sh sh or bash

build-image

Key Type Default Constraints
dockerfile string Dockerfile 1–500 characters
context string the workspace ≤500 characters
target string the last stage ≤200 characters
buildArgs map of string none scalars are coerced
tags list the short commit sha 1–200 characters each

push-image

Key Type Default Constraints
repository string required 1–200 characters; lowercase, digits and . _ -, 2–128
tags list the short commit sha every tag must also appear in a build-image step

The repository is created by the first push that names it, private. Credentials are injected; there is no login step.

cache

Key Type Default Constraints
key string required 1–500 characters; usually holds a hash()
restoreKeys list none prefix matches, most specific first, ≤500 each
paths list required at least one, ≤500 characters each

Restored at the step's position and saved after the job. A miss never fails the build. A prefix hit is re-saved under the exact key. Caches are scoped to one repository.

artifact

Key Type Default Constraints
name string required 1–200 characters
paths list required at least one, ≤500 each
retentionDays integer the organization's setting 1–90

Downloadable from the run page. A failed artifact upload fails the step.

Expressions

Reference Value
commit.sha / commit.short the full oid / 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 the run's id / its number in this repository
run.attempt 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 env var in scope at that point
secrets.NAME only when the job lists NAME under secrets:
Function Arguments Example
join(a, b, …, separator) 2–16 join(repo.name, commit.short, '-')
lower(value) / upper(value) 1 lower(branch)
slice(value, start[, end]) 2–3 slice(tag, 1) → 1.2.3 from v1.2.3
replace(value, from, to) 3 replace(branch, '/', '-')
hash('path') 1 sha256 of that file at the run's commit; literal paths
Condition Where
success(), failure(), cancelled(), always() a step's if: only
==, != against a literal a job's if: or a step's if:

Every value resolves before the machine boots, so the runner receives literal strings. A misspelled reference, an unknown function, the wrong argument count, a status function in a value or in a job's if:, an env name not in scope, and a secrets name the job did not list are all errors on the workflow file, reported against the exact key:

jobs.publish.steps[0].push-image.tags[0]: unknown reference "taag"

Secrets

A job reads a secret only when the job lists it and the secret is granted to the actions consumer:

POST /kms/api/secrets/{secretId}/grants
{ "consumer": "actions" }
Behaviour Detail
Scope only the job that listed the name; a sibling job does not get it
Version always the active version, so a rotation needs no workflow change
Transport decrypted while the plan is built, sent to the machine over TLS
Storage never in the workflow file, the repository, the image or the run's record
Access log every resolution recorded as consumer actions, context workflow job
Grant expiry a grant may carry a ttlDays, after which it counts as absent
Log masking every value printed by a step is replaced by ***, see below

Masking in logs

Before a log line leaves the machine, every secret the run was given is replaced by ***: the secrets its jobs list, the registry password of push-image and the token the run clones with. The same happens to a job's error message. The runner masks:

  • the value itself, however the output was split into writes (a value printed one character at a time is still masked);
  • each line of a multi-line value, such as a PEM key, on its own;
  • the value in base64 (also inside a longer base64 text, such as a Basic authorization header), URL-encoded and JSON-escaped.

A value shorter than 4 characters is not masked, because masking it would black out ordinary output. Masking is a safety net, not a guarantee: a step that transforms a secret in another way (reversing it, hashing it, printing every second character) prints the result in clear. Treat anyone who can read a run's logs as someone who might see what the run's steps print.

A step name is shown to everyone who can read the run, so ${{ secrets.NAME }} in a name: shows as *** too.

What is not supported

  • A matrix built from an expression (fromJSON(…)): only fixed lists.
  • Reusable or composite workflows.
  • Service or sidecar containers alongside a job.
  • Self-hosted Linux runners: a runs-on: linux job always runs on a platform machine. runs-on: macos runs on one of the organization's own registered runners (see the CI/CD guide).
  • Manual dispatch. on: manual: parses and satisfies the "at least one trigger" rule, but only Re-run starts a run outside an event.
  • More than one attempt per run: ${{ run.attempt }} is always 1.
  • Steps other than run, build-image, push-image, cache and artifact.

Troubleshooting

Symptom Cause Fix
the file is reported invalid after a push the workflow does not parse the console names the key; the push itself always lands
Unrecognized key: image on a step image belongs on the job, not the step move it up one level
unknown reference "taag" a misspelled expression the message lists every supported reference
secrets.NPM_TOKEN is not available the job did not list the name add it to that job's secrets:
Secret "NPM_TOKEN" is not granted to actions no actions grant, or its ttlDays ran out grant it under Secrets → Consumers; no job starts until then
Secret "NPM_TOKEN" is not defined in this organization a typo, or a secret in another organization check the name under Secrets
success() is only available in an if: condition a status function used as a value use it in a step's if:
a cache never hits the key changes every run and there are no restoreKeys add a prefix under restoreKeys; a prefix hit re-saves under the key
Did this page help you?