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
- Create the secret under Secrets with exactly the name the workflow uses (
NPM_TOKENfor${{ secrets.NPM_TOKEN }}). - 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.
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.On any Linux machine (x64 or arm64), one command downloads the pinned runner release, checks its SHA-256, registers it as the user
ews-runnerand 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--uninstallremoves 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.--ephemeraltakes one job and then retires the runner.In a workflow,
runs-on: self-hostedorruns-on: [self-hosted, linux, gpu]. A runner takes a job only if it carries every label the job names (case-insensitive; the runner addsself-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 thegithub,inputs(typed: a boolean input istrue/false, not text),varsandneedscontexts andsuccess(),failure(),always(),cancelled(). A job that is not run shows not run: …; a run whose every job was skipped ends at once.needs.<job>.outputsandneeds.<job>.resultreach the jobs after it.runs-onmay 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, withwith:(which may readneeds.*.outputs) as the called file'sinputsandsecrets: inheritor asecrets: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-artifactandactions/download-artifact(v4 to v7, and actions that use them, such asupload-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, forretention-days(default 30, at most 90), and then deleted. Downloading another run's artifacts (run-idwithgithub-token) is not supported.Caches:
actions/cache(v4, v5) and the caching ofsetup-node,setup-go,setup-pythonand 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_TOKENand 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-onlabels are all among the pool's goes to that pool — with or withoutself-hostedin the file, and also whenruns-onis an expression that resolves fromvarsorinputs(${{ (vars.CI_RUNNER_16 == 'hetzner-16' && 'hetzner-16') || 'ubuntu-latest-16-core' }}). Give a poolubuntu-latestandubuntu-24.04and 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, betweenminSize(always on) andmaxSize. 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: truetrusted 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 anenvironment:orid-token: writeis the machine's last: it is destroyed afterwards, so nothing of a deployment is on the disk a later job sees.cleanMachinePerJob: truedestroys 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 passwordlesssudofor therunneruser, as on GitHub's hosted runners; toolchains come fromsetup-*actions into/opt/hostedtoolcache. - ARM. Sizes
a-2,a-4,a-8anda-16are ARM machines (ass-*): give such a poolubuntu-24.04-arm(GitHub's ARM label) and those jobs run on ARM, with the same tools,ghand runner built for arm64. Its machines reportarm64instead ofx64, and its pre-built image is its own. - Pre-built image. With
prebuiltImageon (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: falsekeeps a pool on stock Ubuntu. - Starting from zero. No machine waits in between?
minSize: 1keeps one on (the job starts at once);spare: 1keeps 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:
- When the job's
needsare done, Deutsche Cloud pushes a branchews-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 asenvvalues (needs.build.outputs.versionreadsenv.EWS_NEEDS_BUILD_VERSION); the original commit, ref and event areEWS_ORIGINAL_SHA,EWS_ORIGINAL_REFandEWS_ORIGINAL_EVENT. - 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 itsoutputs:come back (uploaded by a generated last step as the artifactews-handoff-outputs) for the jobs after it. - 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'spermissions: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 butid-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 withPATCH /git/api/repositories/{repoId}{ "defaultWorkflowPermissions": "permissive" }(git:UpdateRepository). - Where it goes.
GITHUB_API_URLishttps://git.<your EWS domain>/api/v3,GITHUB_GRAPHQL_URL…/api/graphql,GITHUB_SERVER_URLthe git host, andGH_HOSTnames it, soghworks as written. For a host that is not github.comghreadsGH_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 underpermissions:, 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_TOKENfires webhooks but no workflow (a job that pushes a version bump would otherwise start itself again).workflow_dispatchthrough 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
needsbetween them run at the same time on that machine. - Each job runs in a container from the image for its
runs-onlabel;container:replaces it;services:start next to it. As on GitHub, a job reaches a service atlocalhoston the port it maps underports:; a job withcontainer:reaches it by service name. - Steps run as the user
runner(uid 1001) with passwordlesssudo, 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 alsoless,rsync,sqlite3,tree,lsof,nc,dig,ping,vim,nano,shellcheck, a currentgh,mvn,psqlandmysql, and/usr/share/dotnetis writable forsetup-dotnet. It is not the full 20 GB GitHub image: install anything else in a step (sudo apt-get install -y …) or with asetup-*action. - Docker is available inside jobs;
docker buildanddocker runwork. 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,releaseandworkflow_run(pull_request_target,issues, …).workflow_run: requestednever fires;completeddoes. - On the one-machine-per-run hosted machines,
permissions:scopes other thanid-tokenand 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: writegets them (runner_environment: self-hosted), butews/configure-credentialsdoes not run there yet, so request the token withcurlorcore.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 orenvironmentclaim. - 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_requesttypedequeued(GitHub's merge queue mechanics; this platform's queue re-queues itself).ready_for_reviewandconverted_to_draftfire when a pull request is marked ready or turned back into a draft (console,POST …/pulls/{n}/readyor…/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$TMPDIRinstead, or usedocker cp. Paths elsewhere in the job (outside the workspace and$TMPDIR) do not exist fordocker run -vat all. - Actions that hard-code
api.github.cominstead of readingGITHUB_API_URL(for exampleactions/first-interactionv3) talk to GitHub, not to Deutsche Cloud;actions/attest-build-provenancerefuses 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 |