# Run Windows jobs on GitHub

Hand a workflow's Windows jobs to GitHub through the repository's push mirror, while the run here waits for them like any other job.

Deutsche Cloud runs no Windows machines. A repository that pushes to GitHub hands its `windows-*` jobs
to GitHub Actions there; the minutes are GitHub's and billed by GitHub.

## Prerequisites

- A push mirror from the repository to a GitHub repository (see
  [Configure a push mirror](/docs/git/guide/configure-a-push-mirror)), with GitHub Actions enabled
  there.
- The run's Linux jobs run on a runner pool or your runners, not on the one-machine-per-run hosted
  machines (give the organization a runner pool with `ubuntu-latest`; see
  [Create a runner pool](create-a-runner-pool.md)).
- The secrets the Windows job reads, as repository secrets on GitHub.

## Hand the job over

Nothing in the workflow changes. When the Windows job's `needs` are done:

1. Deutsche Cloud pushes a branch whose name starts with `ews-handoff/` to the GitHub repository: the
   run's commit, with `.github/workflows/` replaced by one generated workflow holding only that job,
   started by a push to exactly that branch, so no other workflow there runs.
2. The outputs of the jobs it needs arrive as environment values (`needs.build.outputs.version`
   reads `env.EWS_NEEDS_BUILD_VERSION`), and the original commit, ref and event as
   `EWS_ORIGINAL_SHA`, `EWS_ORIGINAL_REF` and `EWS_ORIGINAL_EVENT`.
3. The job's log here links GitHub's run, and the commit status `github/<job>` shows it on the
   commit, where a branch protection rule can require it.

## Result

When GitHub's run ends, its conclusion is the job's, and its `outputs:` come back for the jobs
after it. The branch is then deleted. Cancelling the run here cancels GitHub's run.

- When GitHub starts no run within 15 minutes, the job fails with "GitHub started no run on … within
  15 minutes (Actions disabled, or a ruleset refused the branch?)".
- A matrix leg is not handed off: "a matrix leg is not handed off yet; give the Windows job its own
  job key".
- Without a push mirror, or when the run's Linux jobs use the one-machine-per-run hosted machines,
  the Windows job is cancelled with the reason and the rest of the run goes on.

## Related

- [Run GitHub Actions workflows](run-github-actions-workflows.md)
- [Configure a push mirror](/docs/git/guide/configure-a-push-mirror)
