GitHub Actions workflows

Run .github/workflows files as they are: triggers, matrix, services, actions.

What it is

Workflow files in .github/workflows/ run on Deutsche Cloud as they are. Push a repository that already has GitHub Actions workflows and its pushes, pull requests, schedules and manual starts run here, with uses: actions fetched from GitHub. Runs appear under CI in the console and under Git → Repositories → Actions, next to runs of workflows in our own format (.dcloud/workflows/, see Workflow syntax).

Concepts

Term Meaning
Workflow A .yml or .yaml file directly in .github/workflows/. The directory decides the format: files there are read as GitHub Actions, files in .dcloud/workflows/ as ours.
Job row One line on the run page per job, and per matrix combination when the matrix is a fixed list, e.g. test (20) and test (22).
Step row Set up job, one row per step of the file, Complete job — as on GitHub. Action downloads appear under Set up job, post-steps (cache save) under Complete job.
Runner The machine a run gets. The whole run — every job — executes on one fresh Linux machine that is deleted afterwards.
runs-on ubuntu-latest, ubuntu-24.04, ubuntu-22.04, ubuntu-20.04 and linux run in an Ubuntu image with Node, git, Docker and common build tools. self-hosted (with any other labels) runs on a runner you registered — see Run jobs on your own machine.
Secret ${{ secrets.NAME }} reads a Deutsche Cloud secret of that name that is granted to Actions for this repository.

How to

Run an existing GitHub workflow

Push the repository with its .github/workflows/ directory unchanged. Every workflow whose on: matches the push starts a run. Nothing needs converting.

Give a workflow its secrets

  1. Create the secret under Secrets with exactly the name the workflow uses (NPM_TOKEN for ${{ secrets.NPM_TOKEN }}).
  2. Under the secret's Consumers, grant it to Actions for this repository.

The person whose push (or pull request, or manual start) triggered the run must be allowed secrets:GetSecretValue on it. Secret values are masked as *** in logs.

A name the workflow reads that does not exist in your organization is empty, as on GitHub. A name that exists but is not granted to this repository, or that the triggering person may not read, stops the run with a message saying which.

Masking covers every log line the runner sends, including what a step prints in pieces, each line of a multi-line secret, and the secret in base64, URL-encoded or JSON-escaped form; the rules are the same as for the platform's own workflow format (Masking in logs).

Start a workflow by hand

The workflow needs on: workflow_dispatch. Start it from the API — the CLI and the MCP server expose the same operation:

curl -X POST "$EWS/ci/api/repositories/$REPO_ID/workflows/dispatch" \
  -H "Authorization: EWS-ACCESS-KEY $KEY" -H 'Content-Type: application/json' \
  -d '{ "path": ".github/workflows/release.yml", "ref": "main", "inputs": { "channel": "beta" } }'

ref is a branch or tag (the default branch when left out). Inputs you do not pass take the defaults the workflow declares. This needs ci:StartWorkflow on the repository. The same call starts an .dcloud/workflows/ file that declares on.manual.

Run jobs on your own machine

GitHub's own Actions runner (github.com/actions/runner, unmodified) registers to Deutsche Cloud the way it registers to GitHub.

  1. CI → Runners → Add runner (or POST /ci/api/runners/registration-tokens, optionally with { "repositoryId": "…" } to limit it to one repository). You get a one-time token that expires in 15 minutes and the exact command.

  2. On any Linux machine (x64 or arm64), one command downloads the pinned runner release, checks its SHA-256, registers it as the user ews-runner and starts it as a systemd service:

    curl -fsSL https://console.platform-development.deutschecloud.app/ci/api/runners/install-linux.sh | sudo bash -s -- \
      --url https://git.<your EWS domain>/<org>[/<repo>] --token <token> --labels gpu

    --uninstall removes it again. Or do it by hand, exactly as with GitHub (any OS the runner supports):

    mkdir actions-runner && cd actions-runner
    curl -fsSL -o runner.tgz https://github.com/actions/runner/releases/download/v2.338.2/actions-runner-linux-x64-2.338.2.tar.gz
    tar xzf runner.tgz
    ./config.sh --url https://git.<your EWS domain>/<org>[/<repo>] --token <token> --labels gpu --disableupdate
    ./run.sh        # or: sudo ./svc.sh install && sudo ./svc.sh start

    --url …/<org> registers it for every repository of the organization, …/<org>/<repo> for that repository only. --ephemeral takes one job and then retires the runner.

  3. In a workflow, runs-on: self-hosted or runs-on: [self-hosted, linux, gpu]. A runner takes a job only if it carries every label the job names (case-insensitive; the runner adds self-hosted, its OS and its architecture on its own).

What a run on your runner shows: the same job and step rows and logs as any other run, under the runner's name in CI → Runners. Jobs run on the machine itself, as on GitHub's self-hosted runners, so the machine needs what the steps use.

Such a job runs run: steps and uses: steps — marketplace actions (actions/checkout@v4, owner/repo/path@ref), local actions (./…) and docker:// images — plus container: and services:, which the runner starts with the machine's own Docker. Marketplace actions are resolved and fetched by Deutsche Cloud: the runner gets each one from Deutsche Cloud, pinned to the commit its tag pointed at, and Deutsche Cloud keeps a copy, so a run never sends its credentials to GitHub and you can see which third-party code ran. Disabling a runner in the console revokes its key at once.

How jobs reach your runners, as on GitHub:

  • Jobs, not runs, go to runners. The jobs of one run spread over every runner that has their labels, in parallel; each runner runs one job at a time. Jobs wait for a free runner as long as one with the labels is online (up to the run's two-hour limit), and fail after 20 minutes only when none is.

  • A job's if: is decided before the job is handed out, with GitHub's own expression engine and the github, inputs (typed: a boolean input is true/false, not text), vars and needs contexts and success(), failure(), always(), cancelled(). A job that is not run shows not run: …; a run whose every job was skipped ends at once.

  • needs.<job>.outputs and needs.<job>.result reach the jobs after it.

  • runs-on may read variables: runs-on: ${{ fromJSON(vars.RUNNERS || '"ubuntu-latest"') }} runs on your runners where the variable holds ["self-hosted","pool"] and on hosted machines (or GitHub's) where it is unset.

  • Reusable workflows in the same repository (uses: ./.github/workflows/deploy.yml) are expanded into one row per called job, caller / job, with with: (which may read needs.*.outputs) as the called file's inputs and secrets: inherit or a secrets: map. Jobs after the call wait for all of its jobs.

  • Environments: a job's environment (also ${{ inputs.environment }} inside a called workflow) applies its branch rules, its variables and its secrets to that job only. A job of an environment with reviewers or a wait timer is not handed to any runner until it is approved, so nothing of that environment — no secret, no OIDC token — reaches a machine before then; the approval works as for hosted runs.

  • Artifacts: actions/upload-artifact and actions/download-artifact (v4 to v7, and actions that use them, such as upload-pages-artifact) work unchanged. Deutsche Cloud serves GitHub's artifact API on the git host; artifacts are kept with the run and downloadable from the run page, for retention-days (default 30, at most 90), and then deleted. Downloading another run's artifacts (run-id with github-token) is not supported.

  • Caches: actions/cache (v4, v5) and the caching of setup-node, setup-go, setup-python and friends work. Entries are the same as on hosted runs, scoped the same way (a pull request reads but never writes main's cache), at most 10 GiB each and immutable once saved, as on GitHub. As on GitHub, an entry not restored or saved for 7 days is deleted, and a repository's entries are cut back to 10 GiB in all, least recently used first (an hourly sweep, which also removes the uploads of jobs that died mid-upload).

  • GitHub's API for the repository: see Call the GitHub API from a job below. On your own runners every job gets its own GITHUB_TOKEN and the API, as on GitHub.

Why Deutsche Cloud changes one line of the artifact actions

@actions/artifact, the library inside the artifact actions, stops before any network call when the server is not github.com or *.ghe.com, assuming GitHub Enterprise Server, which does not have the v4 API. Deutsche Cloud does have it. So when your runner fetches an action that bundles the library, Deutsche Cloud serves the same upstream commit with exactly one line changed (patch ews-artifact-ghes-1):

-    return !isGitHubHost && !isGheHost && !isLocalHost;
+    return !isGitHubHost && !isGheHost && !isLocalHost && process.env['EWS_ACTIONS_RESULTS'] !== '1';

Deutsche Cloud sets EWS_ACTIONS_RESULTS=1 in every job it hands a runner, so the changed archive behaves exactly as upstream anywhere else. The job's Set up job log names each archive Deutsche Cloud changed, with the files and the patched archive's sha256: EWS applied its artifact-compatibility patch ews-artifact-ghes-1 to actions/upload-artifact@ (dist/upload/index.js, dist/merge/index.js; archive sha256:…). Nothing else in any action is changed, and an action without the library is served byte for byte. If a future upstream version no longer contains that line, Deutsche Cloud serves the upstream archive unchanged, says so in the same log, and the step fails with GitHub's own GHES is not supported error until Deutsche Cloud follows.

Not yet on your own runners: reusable workflows from another repository or nested more than one level, a matrix of reusable-workflow calls, and ews/* actions (they fail with that reason). A run whose jobs mix hosted and self-hosted machines fails the hosted jobs with that reason.

Run jobs on machines Deutsche Cloud starts for you (runner pools)

A runner pool is a set of machines of one size that Deutsche Cloud starts and stops for your jobs, each running GitHub's official runner — the same kind of machine as a self-hosted runner, without you installing or scaling anything. Every job gets its own runner and the machine to itself.

dcloud ci runner-pools create --name linux --labels ubuntu-latest --labels ubuntu-24.04 \
  --size s-4 --max-size 10
dcloud ci runner-pools create --name big --labels hetzner-16 --labels ubuntu-latest-16-core \
  --size s-16 --min-size 1 --max-size 30 --spare 2
  • Which jobs go there. A job whose runs-on labels are all among the pool's goes to that pool — with or without self-hosted in the file, and also when runs-on is an expression that resolves from vars or inputs (${{ (vars.CI_RUNNER_16 == 'hetzner-16' && 'hetzner-16') || 'ubuntu-latest-16-core' }}). Give a pool ubuntu-latest and ubuntu-24.04 and the jobs that ran on the one-machine-per-run hosted machines run on per-job machines instead, each with its own token and GitHub's API. Labels a pool does not carry (windows-latest, macos-latest) are not affected.
  • Scaling. When a job for the pool's labels is queued, and every minute besides, the pool asks for as many machines as it has jobs running and waiting, plus spare, between minSize (always on) and maxSize. A machine that becomes idle stays until shortly before its paid hour ends and takes the next job for free; then it goes. The pool's page shows the last decision ("2 running + 3 waiting + 1 spare → 6").
  • Machine reuse. A machine's first job decides what it takes afterwards: its repository, and its trust class — pull request and merge queue builds (code nobody merged yet) or everything else (default branch, tags, manual starts, schedules). The two classes never share a machine. With shareTrustedMachines: true trusted jobs of every repository of the organization share machines (fewer machines bought when several repositories push at once); pull request jobs stay per repository. When jobs wait and the pool is at its size, an idle machine that none of them may use is replaced by a fresh one. A job with an environment: or id-token: write is the machine's last: it is destroyed afterwards, so nothing of a deployment is on the disk a later job sees. cleanMachinePerJob: true destroys every machine after its job. Between jobs every container, network and volume a job left is removed and the work directory emptied.
  • What runs. Ubuntu 24.04 with Docker (and Compose, Buildx), git, git-lfs, jq, a compiler, Python, gh, and passwordless sudo for the runner user, as on GitHub's hosted runners; toolchains come from setup-* actions into /opt/hostedtoolcache.
  • ARM. Sizes a-2, a-4, a-8 and a-16 are ARM machines (as s-*): give such a pool ubuntu-24.04-arm (GitHub's ARM label) and those jobs run on ARM, with the same tools, gh and runner built for arm64. Its machines report arm64 instead of x64, and its pre-built image is its own.
  • Pre-built image. With prebuiltImage on (the default) the machines boot from a runner image of your organization with all of the above already installed, and take their first job about a minute sooner: a machine from zero asks for work some 45 seconds after it is ordered, against about 100 from stock Ubuntu. The image is built once per organization and region, shared by its pools: a small builder machine that never runs a job installs everything, removes what is its own (its identity, keys and logs) and is imaged and terminated, all in about five minutes. Until then, and whenever it is being rebuilt or a build failed (shown on the pool, retried after six hours), machines boot stock Ubuntu and install at boot, so a missing image means slower, never broken. It is rebuilt weekly for security updates and when the installed tools change; machines already running keep theirs. The image (runner-image-…) and the builder are yours and billed as such: a few minutes of the smallest size and the image's storage. When no pool uses it any more it is deleted. prebuiltImage: false keeps a pool on stock Ubuntu.
  • Starting from zero. No machine waits in between? minSize: 1 keeps one on (the job starts at once); spare: 1 keeps one more than the work needs.
  • Where it shows. The pool's machines are an auto scaling group runner-pool-<name> and a launch template of the same name in your organization (EC2 → Auto Scaling), billed as instances. Machines prove themselves with their instance identity token; no credential is stored on them.

Creating a pool needs ci:CreateRunnerPool and what its group launches with: autoscaling:CreateLaunchTemplate, autoscaling:CreateAutoScalingGroup and ec2:RunInstances. A runnerGroupId applies a runner group's repository, ref and pull-request rules to the pool.

Run Windows jobs on GitHub

Deutsche Cloud runs no Windows machines. A repository that pushes to GitHub (a push mirror, set up with a token or through Git → Connect GitHub) hands its Windows jobs to GitHub, and the run here waits for them like for any other job:

  1. When the job's needs are done, Deutsche Cloud pushes a branch ews-handoff/<run>-<job> to the GitHub repository: the run's commit with .github/workflows/ replaced by one generated workflow holding only that job. It starts on a push to exactly that branch, so no other workflow of the repository runs. The outputs of the jobs it needs are passed as env values (needs.build.outputs.version reads env.EWS_NEEDS_BUILD_VERSION); the original commit, ref and event are EWS_ORIGINAL_SHA, EWS_ORIGINAL_REF and EWS_ORIGINAL_EVENT.
  2. The job's log here links GitHub's run, and a commit status github/<job> shows it on the commit (a branch protection rule here can require it). When GitHub's run ends, its conclusion is the job's, and its outputs: come back (uploaded by a generated last step as the artifact ews-handoff-outputs) for the jobs after it.
  3. The branch is deleted. Cancelling the run here cancels GitHub's run.

The minutes are GitHub's and billed there. The token needs repo and workflow scope (the App has both). Secrets come from GitHub's own repository secrets, as they would on GitHub. Not handed off: a run whose Linux jobs run on the one-machine-per-run host (give the organization a runner pool with ubuntu-latest), a matrix leg (give the Windows job its own key), and shadow runs of a mirror (they write nothing to GitHub). If GitHub starts no run within 15 minutes (Actions disabled, a ruleset refusing the branch), the job fails saying so.

Call the GitHub API from a job

Workflows talk to GitHub's API all the time: gh pr comment, actions/github-script, dorny/paths-filter, a step that cancels the other runs of a commit, a release action. On Deutsche Cloud the same calls reach Deutsche Cloud, with no change to the workflow:

  • The token. Every job gets its own GITHUB_TOKEN (${{ github.token }}, ${{ secrets.GITHUB_TOKEN }}). It works for this repository only, ends when the job ends, and can do what the workflow's permissions: say — the job's own block, else the workflow's, else the repository's default. The job's log shows them under Set up job → GITHUB_TOKEN Permissions, as on GitHub.
  • The default when a workflow says nothing is the repository's workflow permissions setting, GitHub's two choices: restricted (contents: read, packages: read) or permissive (read and write on everything but id-token). New repositories are restricted, as on GitHub; repositories that existed before 2026-11-18 are permissive, so nothing changed for them; an import from GitHub copies the source's setting when the import token may read it (otherwise restricted). Change it with PATCH /git/api/repositories/{repoId} { "defaultWorkflowPermissions": "permissive" } (git:UpdateRepository).
  • Where it goes. GITHUB_API_URL is https://git.<your EWS domain>/api/v3, GITHUB_GRAPHQL_URL …/api/graphql, GITHUB_SERVER_URL the git host, and GH_HOST names it, so gh works as written. For a host that is not github.com gh reads GH_ENTERPRISE_TOKEN; Deutsche Cloud sets it to the job's token in every job (a workflow's own value wins).
  • What a refusal says. A call the token's permissions do not allow answers 403 with Resource not accessible by integration: the job's GITHUB_TOKEN needs issues: write — add it under permissions:, and is recorded in the audit log, allowed or not, like every write.
  • As on GitHub, a job's token starts no new run: a push, a tag, a release or a pull request made with GITHUB_TOKEN fires webhooks but no workflow (a job that pushes a version bump would otherwise start itself again). workflow_dispatch through the API is the exception, as on GitHub; that run's secrets follow the person whose push or start began the job's run.

What is served, with GitHub's JSON, Link pagination and media types:

Area Endpoints Permission
Repository and code the repository, branches, git/ref, git/matching-refs, git/commits/{sha}, commits, commits/{ref}, commits/{sha}/pulls, compare/{base}...{head}, contents/{path} contents: read (metadata: always)
Pull requests list, get (also as diff or patch), files, commits; create (POST pulls), edit and close (PATCH pulls/{n}) pull-requests
Issues and comments list (with labels, state), create, get, edit and close; comments on an issue or a pull request (issues/{n}/comments), edit or delete your own comment (issues/comments/{id}) issues, or pull-requests for comments
Labels list, get, create (already_exists for gh label create --force), edit; add, set and remove on an issue or pull request issues or pull-requests
Statuses and checks POST statuses/{sha}, commits/{ref}/status(es); check runs: commits/{ref}/check-runs, check-suites, POST check-runs, PATCH check-runs/{id}, annotations (empty). A check run an action creates is kept as a commit status of its name statuses, checks
Actions runs (filters head_sha, event, status, branch, created), a run and its attempts, jobs, a job, a job's log, cancel and force-cancel, re-run; workflows, a workflow's runs, dispatches (also return_run_details); artifacts of a run or the repository, an artifact, its zip, delete actions
Releases list, latest, by tag, get, create (a new tag needs contents: write), edit, publish, delete; assets: list, upload (upload_url, at /api/uploads/…), download, delete contents
Code scanning SARIF upload and its status (codeql-action/upload-sarif) security-events: write
Security advisories GET /advisories?ecosystem=…&affects=name@version,… (npm, pip, go, rust, composer; up to 1000 packages), answered from Deutsche Cloud's own vulnerability database: the packages asked about are checked offline, never sent elsewhere. first_patched_version is the fix of the asked version's line; vulnerable_version_range is < that fix. A listing without affects, and type=unreviewed or malware, are not served (422, or empty) any token
GraphQL (/api/graphql) viewer, repository { issue, pullRequest, issueOrPullRequest, issues, pullRequests, labels, assignableUsers, ref, object, defaultBranchRef, mergeQueue }, commit history with status, search(type: ISSUE), node(s); mutations addComment, createIssue, closeIssue, reopenIssue, updateIssueComment, deleteIssueComment, minimizeComment, addLabelsToLabelable, removeLabelsFromLabelable; introspection as the REST equivalent

Ids follow GitHub's habits: a run is its number (GITHUB_RUN_ID), a job's id is also its check run's, node ids in GraphQL are the REST node_ids. Anything not served answers 404 with the path (REST) or a validation error naming the field (GraphQL), never a silent empty answer. Comments a job writes show as github-actions[bot].

Not served: deployments and their statuses (environments are read through Deutsche Cloud's own API), projects, discussions, attestations (actions/attest-build-provenance accepts only github.com), enabling or disabling one workflow, re-running only the failed jobs of a run (the whole run is re-run).

Deploy with no stored secret (OIDC)

A job with permissions: id-token: write can ask for an OpenID Connect token, exactly as on GitHub: ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN are in its environment, and core.getIDToken(), aws-actions/configure-aws-credentials or a plain curl work unchanged. The token is signed by Deutsche Cloud CI's own issuer, https://console.platform-development.deutschecloud.app/ci/api/oidc (discovery at /.well-known/openid-configuration, keys at /jwks), and carries GitHub's claims: sub is repo:<org>/<repo>:ref:refs/heads/main, repo:<org>/<repo>:environment:production for a job with an environment, or repo:<org>/<repo>:pull_request; plus repository, repository_id, ref, sha, environment, workflow_ref, job_workflow_ref, event_name, run_id, actor and runner_environment (ews-hosted or self-hosted). Any relying party can trust it — Deutsche Cloud's own STS, AWS, Vault.

To deploy to Deutsche Cloud with it, one step:

permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4
      - uses: ews/configure-credentials@v1
        with:
          role-to-assume: rn:ews::<org-id>:iam:role/<role-id>
      - run: |
          docker build -t "$EWS_REGISTRY/web:$GITHUB_SHA" .
          docker push "$EWS_REGISTRY/web:$GITHUB_SHA"
      - uses: ews/deploy@v1
        with:
          app: web
          image: ${{ env.EWS_REGISTRY }}/web:${{ github.sha }}

ews/configure-credentials trades the job's token for credentials of the role (at most one hour), exports DCLOUD_ACCESS_KEY and DCLOUD_API_URL (and the same under the older EWS_ names) for the CLI and later steps, and signs Docker in to your registry (DCLOUD_REGISTRY and EWS_REGISTRY, output registry). Set up once: IAM → Identity providers → Add Deutsche Cloud CI, then on the role a trust policy naming the repository (and branch or environment) — see IAM. Every token issued is in the audit log (ci:CreateIdToken, with run, job and sub), and every exchange too (iam:AssumeRoleWithWebIdentity).

ews/… actions are served by Deutsche Cloud itself and never looked up on GitHub — on GitHub, dcloud is somebody else's account. A workflow that must also run on GitHub's runners names the action by its path in a repository you control on GitHub; the inputs are the same there (api-url is then required, since GitHub does not know your console). A role that already trusts GitHub. A workflow moved here keeps its trust policy: POST /iam/api/roles/{id}/trust-ci (dcloud iam roles trust-ci <id>) gives every statement that trusts GitHub Actions a twin for Deutsche Cloud CI, with repo:<owner>/<repo> mapped to the repository imported or mirrored here (repo:<organization>/<repo>). GitHub's jobs keep assuming the role. Statements that pin only by GitHub's numeric ids are listed, not twinned. For a relying party outside Deutsche Cloud (Entra ID, a cloud's workload identity), add a federated credential with the issuer https://console.platform-development.deutschecloud.app/ci/api/oidc and the same subject format: repo:<organization>/<repo>:ref:refs/heads/main, …:environment:<name> or …:pull_request.

Use variables (vars)

${{ vars.NAME }} reads configuration variables — plain text, shown in the console, never masked. Set them for the organization (PUT /ci/api/variables/NAME), a repository (…/repositories/{repoId}/variables/NAME) or an environment (…/repositories/{repoId}/environments/{env}/variables/NAME) with { "value": "…" }. In a job with that environment the environment's value wins, then the repository's, then the organization's — as on GitHub. Names are upper-cased; GITHUB_ is reserved.

Protect a deployment with an environment

A job that says environment: production (or environment: ${{ inputs.environment }}) deploys to that environment of the repository. A workflow that names one creates it, without rules. Rules (PUT /ci/api/repositories/{repoId}/environments/production, dcloud ci environments put, or the MCP tool of the same name):

Rule Effect
deploymentBranchPolicy: protected Only branches with a branch protection rule may deploy. Other refs fail the job: Branch "x" is not allowed to deploy to production…
custom + deploymentPatterns Only matching branches ({type: branch, pattern: release/*}) or tags ({type: tag, pattern: v*})
reviewers (up to six IAM users) The job waits at its first step, Wait for production protection rules, until one of them approves (or rejects) it
preventSelfReview The person who started the run cannot approve it
waitTimerMinutes The job waits that long before it continues

Waiting jobs are listed by GET /ci/api/repositories/{repoId}/approvals; approve with POST /ci/api/approvals/{id}/review { "decision": "approve" } (CLI: dcloud ci environments review). Approving needs ci:ReviewDeployments and a place on the reviewer list; both decisions are in the audit log. A job is held for at most 5 h 30 min, then expires. The rule is enforced on the server, not only by the waiting step: an unapproved job gets no OIDC token.

Environment secrets are your organization's secrets environment with the same slug: in a job with environment: prod, ${{ secrets.X }} reads X from the prod environment when it has one. In an environment with reviewers that is refused — on Deutsche Cloud's hosted machines every job of a run runs side by side, so a secret handed to the run could be read before anyone approved. Use OIDC there; it needs no secret.

Run on a schedule

on: schedule: - cron: '…' runs from the repository's default branch, in UTC, as on GitHub. The schedule takes effect with the next push to the default branch, and scheduled runs execute with the permissions of the person who made that push. A schedule fires at most every five minutes.

Lift GitHub's download rate limit

actions/setup-node, setup-go, setup-python and similar actions download toolchains from GitHub. Without a token, GitHub allows 60 such API calls an hour per address. Create a secret named GITHUB_TOKEN holding a GitHub token with no scopes, grant it to Actions for the repository, and those actions use it.

Check a workflow file before pushing

POST /ci/api/workflows/validate with { "source": "<file contents>", "path": ".github/workflows/ci.yml" } answers { valid, issues }.

Reference

Triggers

on: Runs when Filters honoured
push A branch or tag is pushed branches, branches-ignore, tags, tags-ignore, paths, paths-ignore
pull_request A pull request is opened (opened), reopened (reopened) or its branch is pushed (synchronize); with types: also closed, edited, labeled, unlabeled (github.event.label.name) branches, branches-ignore, paths, paths-ignore, types
merge_group The merge queue builds a pull request with everything ahead of it (checks_requested) branches, branches-ignore (the base branch), types
workflow_dispatch Started through the dispatch API inputs: defaults applied; required, boolean, number, choice and environment checked before the run exists
schedule Its cron matches, on the default branch —
release A release is created, published (then released or prereleased), edited or deleted types — without it, one release starts the workflow once per action, as on GitHub; use types: [published]
workflow_run A run of a named workflow completed; runs on the default branch workflows (names, globs), types: [completed], branches (of the run that completed); chains stop after three

Patterns follow GitHub's rules: * does not cross /, ** does, [0-9] or [abc] is one character from the range or list, + and ? repeat the character before them, ! negates, and the last matching pattern wins. A file whose triggers are all events Deutsche Cloud does not produce is skipped, not reported as an error.

A pull request run builds the tip of the pull request's branch.

What runs where

  • One machine per run, created for it and deleted when it ends. Jobs without needs between them run at the same time on that machine.
  • Each job runs in a container from the image for its runs-on label; container: replaces it; services: start next to it. As on GitHub, a job reaches a service at localhost on the port it maps under ports:; a job with container: reaches it by service name.
  • Steps run as the user runner (uid 1001) with passwordless sudo, home /home/runner, as on GitHub's hosted runners.
  • The Ubuntu image carries Node, Python, Go tool caches, git, Docker CLI, jq, yq, make, gcc, zip, curl, wget, and also less, rsync, sqlite3, tree, lsof, nc, dig, ping, vim, nano, shellcheck, a current gh, mvn, psql and mysql, and /usr/share/dotnet is writable for setup-dotnet. It is not the full 20 GB GitHub image: install anything else in a step (sudo apt-get install -y …) or with a setup-* action.
  • Docker is available inside jobs; docker build and docker run work. A container you start can mount a temporary directory from the job (d=$(mktemp -d), anything under $TMPDIR) both ways, as on GitHub, and can mount the workspace (-v "$PWD:/src") to read the repository as checked out.
  • Each job gets its own copy of the repository at the run's commit, with its history, when it runs actions/checkout; parallel jobs never share a working directory.
  • Jobs whose services publish a fixed host port (ports: ['5432:5432']) run one at a time, since the whole run shares one machine; everything else runs in parallel.

Features

Feature Supported
jobs, needs, job outputs, if: on jobs and steps Yes
strategy.matrix with include / exclude, fail-fast, matrices from fromJSON(…) Yes
env at workflow, job and step level; defaults.run Yes
Expressions and functions (contains, startsWith, hashFiles, toJSON, …) Yes
GITHUB_OUTPUT, GITHUB_ENV, GITHUB_PATH, GITHUB_STEP_SUMMARY, workflow commands Yes
uses: JavaScript, composite and Docker actions from GitHub; local ./ actions Yes
actions/cache and setup-* caching Yes, kept across runs, scoped like GitHub: a pull request reads but never writes main's cache
actions/upload-artifact / download-artifact (v4) Yes; uploaded artifacts are also kept with the run and downloadable from the run page
services:, container: Yes
Reusable workflows (jobs.<id>.uses) Yes
concurrency: (workflow level) with group and cancel-in-progress, expressions included Per repository and group one run in progress and one pending; a newer run cancels the pending one, cancel-in-progress the running one too. The pending run waits with no machine and starts within a minute of the group freeing up
concurrency: on a job, with group and cancel-in-progress, expressions with the job's contexts (matrix, needs, inputs) On runners and runner pools: per repository and group one job running and one waiting; a newer waiting job cancels the older one, cancel-in-progress the running one too (its runner stops it within a minute). The waiting job gets no machine
timeout-minutes, continue-on-error Yes

Contexts that differ from GitHub

Context Value on Deutsche Cloud
github.repository <organization>/<repository>
github.server_url https://github.com — it is where uses: actions come from
github.run_number The run's number on Deutsche Cloud (#42)
github.actor The username of the person who triggered the run
github.token On runners (yours, or a runner pool): the job's own token, see Call the GitHub API from a job. On the one-machine-per-run hosted machines: your GITHUB_TOKEN secret if you created one, otherwise empty
vars.* Organization, repository and environment variables

Permissions

Action Needed for
ci:StartWorkflow Starting a workflow through the dispatch API
ci:RerunWorkflow Re-running; a re-run repeats the original event and identity (github.actor); the person who re-ran it grants nothing
ci:ManageRunners A registration token: on rn:ews::{org}:ci:repository/{repoId} for a one-repository runner, on ci:* for an organization runner
ci:DescribeRunners Listing runners
ci:ListVariables, ci:PutVariable, ci:DeleteVariable Variables: on ci:* for the organization's, on the repository for its own and its environments'
ci:ListEnvironments, ci:PutEnvironment, ci:DeleteEnvironment Environments and their rules, and the list of waiting approvals
ci:ReviewDeployments Approving or rejecting a waiting job (also: being on the environment's reviewer list)
git:CreateRelease, git:UpdateRelease, git:DeleteRelease Releases, which start on: release workflows; a new tag also needs git:PushRepository

What is not supported

  • runs-on: windows-* on Deutsche Cloud's machines. With a push mirror to GitHub they run on GitHub instead (Run Windows jobs on GitHub); without one they show as cancelled with the reason, and the rest of the run proceeds.
  • runs-on: macos-* without a connected Mac that runs each job in a fresh VM, and macOS jobs in the same run as jobs on Deutsche Cloud's one-machine-per-run Linux hosts (give the organization a runner pool with the Linux labels, and both run in one run). See macOS runners.
  • Events other than push, pull_request, merge_group, workflow_dispatch, schedule, release and workflow_run (pull_request_target, issues, …). workflow_run: requested never fires; completed does.
  • On the one-machine-per-run hosted machines, permissions: scopes other than id-token and GitHub's API (on runners both work).
  • OIDC tokens in jobs of a called reusable workflow on Deutsche Cloud's hosted machines (on your own runners they work). On your own runners a job with id-token: write gets them (runner_environment: self-hosted), but ews/configure-credentials does not run there yet, so request the token with curl or core.getIDToken(); a job of an environment with reviewers gets its token once approved, since it only starts then.
  • An environment: built from anything but a literal or ${{ inputs.x }} (for example ${{ matrix.env }}): the job runs without an environment — no environment variables, secrets or environment claim.
  • Environment secrets in an environment with reviewers (see above).
  • Job-level concurrency: on the one-machine-per-run hosted machines (on runners and runner pools it is honoured, see Features).
  • pull_request type dequeued (GitHub's merge queue mechanics; this platform's queue re-queues itself). ready_for_review and converted_to_draft fire when a pull request is marked ready or turned back into a draft (console, POST …/pulls/{n}/ready or …/draft, gh pr ready [--undo]).
  • Seeing the job's own changes through a workspace mount: a container you start with -v "$PWD:…" sees the repository as checked out, not files a step has created or changed since, and what it writes there does not appear in the job. Write to a directory under $TMPDIR instead, or use docker cp. Paths elsewhere in the job (outside the workspace and $TMPDIR) do not exist for docker run -v at all.
  • Actions that hard-code api.github.com instead of reading GITHUB_API_URL (for example actions/first-interaction v3) talk to GitHub, not to Deutsche Cloud; actions/attest-build-provenance refuses any server but github.com.

Troubleshooting

Symptom Cause Fix
A job shows macOS jobs can't share a run with jobs on Deutsche Cloud's one-machine-per-run Linux hosts The run also has ubuntu-* jobs and no runner pool carries their labels Create a runner pool with those labels (then one run does both), or move the macOS jobs to their own workflow file
A macos-latest job stays queued No connected Mac that runs jobs in a fresh VM is online See macOS runners
The run fails with Secret "X" is not granted to Actions The secret exists but is not granted to this repository Grant it under Secrets → Consumers
setup-node fails with an API rate limit error GitHub's anonymous limit for toolchain downloads Create a GITHUB_TOKEN secret, see Lift GitHub's download rate limit
A job shows not run: its if: condition was false… Its if: was false, or a job in its needs did not succeed Check the job it needs
A scheduled workflow never runs Schedules are read from the default branch when it is pushed Push to the default branch after adding the schedule
Did this page help you?