> ## Documentation Index
> Fetch the complete documentation index at: https://docs.airshipci.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Move your workflows

> Let the dashboard read your workflows, suggest runners, and open the pull request that moves your jobs.

You do not have to write `airship.yaml` or edit `runs-on` by hand. **Move
workflows** reads a repository's `.github/workflows`, suggests a runner for
each kind of machine your jobs use today, and shows the exact changes before
anything is written. Open it from **Repositories → Move workflows**, or from
the last step of **Set up**.

Nothing changes in the repository until you merge the pull request it opens.
Your choices are kept in the browser, so you can stop at any step and pick it
up later; every step can be skipped and revisited.

![The Set up page's last step: activated repositories, each with a Move workflows button](https://mintcdn.com/airship/IRpWZElYhTMx-cpZ/images/dashboard/setup-workflows-light.webp?fit=max\&auto=format\&n=IRpWZElYhTMx-cpZ\&q=85\&s=31eca2e5ef20ba144484137a5b21a50c)

> [!NOTE]
>
> Only organization owners can move workflows: it shows the content of
> repositories some members may not be able to read on GitHub.

**1. Pick a repository**

Any repository the GitHub App can see, activated or not. Ones you have
started show **Resume**.

![The repository list, with a search field and a Select button on each repository](https://mintcdn.com/airship/IRpWZElYhTMx-cpZ/images/dashboard/move-workflows-repository-light.webp?fit=max\&auto=format\&n=IRpWZElYhTMx-cpZ\&q=85\&s=83394f8f7cc5ccff167803ed2544a3ad)

**2. Choose jobs**

Every job in every workflow on the default branch, with its `runs-on` as
written today. Jobs on GitHub-hosted Linux runners are picked for you;
tick or untick anything else.

Some jobs cannot be moved automatically, and say why: a `runs-on` computed
by an expression such as `${{ matrix.os }}`, a runner group, or a call to
a reusable workflow. Change those by hand.

![Jobs grouped by workflow file, each with a checkbox, its runs-on label and its platform](https://mintcdn.com/airship/IRpWZElYhTMx-cpZ/images/dashboard/move-workflows-jobs-light.webp?fit=max\&auto=format\&n=IRpWZElYhTMx-cpZ\&q=85\&s=8ce7ee844c674ebb158ef18006a066fe)

**3. Set up runners**

One runner is suggested for each kind of machine the jobs need — Linux,
Linux on Arm, an older Ubuntu — sized at four vCPUs like GitHub's
standard runner, on the cloud you connected. Change the name, cloud,
machine, image, region or spot capacity, add more runners, and choose
which runner each job uses.

Each runner becomes a definition in [`airship.yaml`](https://docs.airshipci.com/configuration/overview),
serving the label `airship-<name>`.

![Runner cards with name, cloud, machine, image and region fields, and a list of where each job runs](https://mintcdn.com/airship/IRpWZElYhTMx-cpZ/images/dashboard/move-workflows-runners-light.webp?fit=max\&auto=format\&n=IRpWZElYhTMx-cpZ\&q=85\&s=47a7413170d266f5ea49bc0d2fdacde8)

**4. Review and ship**

A diff of every file the change writes, checked the same way a job would
read it. Open a pull request into the default branch, or copy or download
the files and commit them yourself. If the repository is not activated
yet, activate it here too.

![Diffs of the new airship.yaml and of each workflow's runs-on lines, with Download files and Open pull request buttons](https://mintcdn.com/airship/IRpWZElYhTMx-cpZ/images/dashboard/move-workflows-review-light.webp?fit=max\&auto=format\&n=IRpWZElYhTMx-cpZ\&q=85\&s=ee34518daa07915688b37e97f94f0742)

Once it is open, the next run after you merge uses your runners.

![Pull request opened, with buttons to review it on GitHub and to activate the repository](https://mintcdn.com/airship/IRpWZElYhTMx-cpZ/images/dashboard/move-workflows-opened-light.webp?fit=max\&auto=format\&n=IRpWZElYhTMx-cpZ\&q=85\&s=0826a84336ca27a69157a6a8a046d62e)

## What changes

* **`airship.yaml`** gains a definition for each new runner. If the
  repository already has one, the definitions are added to the end of its
  `runners:` list and the rest of the file is left as it is.
* **Each moved job's `runs-on`** becomes its runner's label with the run ID
  as a [suffix](https://docs.airshipci.com/configuration/labels.md#always-add-the-run_id-suffix), and for
  a matrix job the leg's index too, so every leg gets a machine of its own:

  ```yaml theme={null}
  runs-on: airship-linux--${{ github.run_id }}
  runs-on: airship-linux--${{ github.run_id }}-${{ strategy.job-index }}
  ```

  Only that value changes. Comments, quoting and everything else in the file
  stay exactly as they were.

A job can also use a label your `airship.yaml` or the organization's
[shared runners](https://docs.airshipci.com/organization/runners.md) already serve.

## Windows and macOS jobs

They are not picked by default. A Windows job needs a runner with a Windows
image ([Windows runners](https://docs.airshipci.com/configuration/windows.md)), and there are no macOS
images; the runner step warns about both before anything is written.

## Opening the pull request

The GitHub App opens the pull request only if it has Contents, Pull requests
and Workflows write access; GitHub refuses an app's changes under
`.github/workflows` without the last one. Without them the dashboard says
which to grant, and you can still download the files and commit them
yourself. See [the GitHub App's permissions](https://docs.airshipci.com/self-hosting/github-app.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.