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 testThere 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.shReference
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
Basicauthorization 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: linuxjob always runs on a platform machine.runs-on: macosruns 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 always1. - Steps other than
run,build-image,push-image,cacheandartifact.
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 |