# Run GitHub Actions workflows

Push a repository with its .github/workflows folder and its workflows run here as they are, with uses actions, matrices, caches and artifacts.

Nothing needs converting. Every `.yml` or `.yaml` file directly in `.github/workflows/` is read as
GitHub Actions, and every one whose `on:` matches an event starts a run. Runs appear on the
repository's **CI** tab next to runs of native-format workflows.

## Prerequisites

- The repository's workflow files, pushed (see [Add a workflow](add-a-workflow.md)).
- The secrets the workflows read, granted to `actions` (see [Give a job a secret](give-a-job-a-secret.md)),
  and the variables they read (see [Set a variable](set-a-variable.md)).

## Where the jobs run

| `runs-on`                                                                       | Where                                                                                                                                                       |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04`, `ubuntu-20.04`, `linux`, `x64` | One fresh Linux machine for the whole run, deleted afterwards; each job in a container of an Ubuntu image. A runner pool with the labels takes them instead |
| Labels of a runner pool                                                         | The pool's machines, one job per machine (see [Create a runner pool](create-a-runner-pool.md))                                                              |
| `self-hosted` and your runners' labels                                          | Your runners (see [Register a runner](register-a-runner.md))                                                                                                |
| `macos-*`, `[self-hosted, macOS]`                                               | Your Macs                                                                                                                                                   |
| `windows-*`                                                                     | GitHub, through a push mirror (see [Run Windows jobs on GitHub](run-windows-jobs-on-github.md)); otherwise the job is cancelled with the reason             |

On the one-machine-per-run hosted machines:

- Jobs without `needs` between them run at the same time. When any job publishes ports, the whole
  run runs one job at a time.
- `container:` replaces the job's image and `services:` start beside it.
- Steps run as the user `runner` (uid 1001) with passwordless `sudo` and home `/home/runner`. The
  image is not GitHub's full image: install anything missing in a step or with a `setup-*` action.
- `uses:` actions are fetched from GitHub.
- A run may last two hours.

One run cannot use these machines and your Macs or runners together:

- With `macos-*` jobs, the run stays on the hosted machines and its macOS jobs are cancelled with
  "macOS jobs can't share a run with jobs on Deutsche Cloud's one-machine-per-run Linux hosts. …".
- With `self-hosted` jobs, the run goes to your runners and its hosted Linux jobs fail with "no
  runner or runner pool here carries this job's runs-on labels … and a run whose other jobs use
  runners cannot also use the one-machine-per-run hosted machines".

Give the organization a runner pool that carries the Linux labels, and one run uses both.

## What starts a run

| `on:`               | Runs when                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `push`              | A branch or tag is pushed; `branches`, `branches-ignore`, `tags`, `tags-ignore`, `paths`, `paths-ignore` apply (a tag push ignores paths)                        |
| `pull_request`      | A pull request is opened, reopened or its branch pushed; with `types:` also `closed`, `edited`, `labeled`, `unlabeled`, `ready_for_review`, `converted_to_draft` |
| `merge_group`       | The merge queue builds a pull request with everything ahead of it                                                                                                |
| `workflow_dispatch` | Started by hand (see [Start a workflow by hand](start-a-workflow-by-hand.md))                                                                                    |
| `schedule`          | Its cron matches, in UTC, on the default branch                                                                                                                  |
| `release`           | A release is created, published, released, prereleased, edited or deleted; use `types:` to pick                                                                  |
| `workflow_run`      | A run of a named workflow completed, on the default branch; chains stop after three                                                                              |

A schedule takes effect with the next push to the default branch and runs as the person who made
that push; it fires at most every five minutes. A file whose triggers are all events Deutsche Cloud
does not produce is skipped, not reported as an error.

## What works

- `jobs`, `needs`, job `outputs`, `if:`, `strategy.matrix` with `include`, `exclude` and
  `fromJSON(…)`, `env`, `defaults.run`, expressions and their functions, `timeout-minutes`,
  `continue-on-error`.
- Workflow-level `concurrency:`: per repository and group, one run in progress and one pending; a
  pending run starts within a minute of the group freeing up. Job-level `concurrency:` works on
  your runners and runner pools.
- `actions/cache`: entries are scoped like GitHub's (a pull request reads the default branch's
  cache but never writes it). On your runners and runner pools an entry is up to 10 GiB and cannot
  be replaced once saved; on the hosted machines a save under the same key replaces it.
- `actions/upload-artifact` and `download-artifact` (v4 and later): artifacts are kept with the run,
  1 to 90 days (30 by default), and downloadable from the run page (see
  [Download an artifact](download-an-artifact.md)).
- `vars.*` (see [Set a variable](set-a-variable.md)), environments (see
  [Protect a deployment with an environment](protect-a-deployment.md)) and OIDC tokens (see
  [Deploy with an OIDC token](deploy-with-oidc.md)).

Contexts differ from GitHub in a few values: `github.repository` is `<organization>/<repository>`,
`github.server_url` is `https://github.com` (where `uses:` actions come from), and on the hosted
machines `github.token` is your secret named `GITHUB_TOKEN` if you created one, otherwise empty. On
your runners and runner pools every job gets its own token (see
[Call the GitHub API from a job](call-the-github-api-from-a-job.md)).

## Result

The run's jobs appear on the run page as on GitHub, one row per job and per matrix combination,
with their steps and logs. See [Not supported](not-supported.md) for what does not run.

## Related

- [Workflows and runs](workflows-and-runs.md)
- [Runners and runner groups](runners-and-groups.md)
