# Migrate to Avrea CI

import { Aside } from '@astrojs/starlight/components';

Start with a build or test workflow. Copy it to `.avrea/workflows/`, use Avrea
runner labels, then compare its results with your existing GitHub Actions run.

## 1. Connect and enable the repository

Install the [Avrea GitHub App](/getting-started/) with access to your repository.
Contact [support@avrea.com](mailto:support@avrea.com) to have Avrea CI and
repository mirroring enabled for that repository.

Review [compatibility and limits](/avrea-ci/compatibility/) before copying
workflows. Keep workflows that need unsupported features on GitHub Actions
until you have adapted them.

## 2. Copy your workflow files

Use the same filenames under `.avrea/workflows/`:

```text
.github/workflows/test.yml   → .avrea/workflows/test.yml
.github/workflows/build.yaml → .avrea/workflows/build.yaml
```

From your repository root, copy one workflow to start:

```sh
mkdir -p .avrea/workflows
cp -i .github/workflows/test.yml .avrea/workflows/test.yml
```

Or copy all workflow files for review:

```sh
mkdir -p .avrea/workflows
find .github/workflows -maxdepth 1 -type f \
  \( -name '*.yml' -o -name '*.yaml' \) \
  -exec cp -i {} .avrea/workflows/ \;
```

The `-i` option asks before overwriting an existing destination. Workflow files
must sit directly inside `.avrea/workflows/`; subdirectories are not discovered.

## 3. Update runner labels and paths

Change every job's `runs-on` to a supported Avrea Linux, macOS, or Windows
label. This includes labels inside matrices. Jobs already using supported
Avrea labels can keep them.

For example, replace `ubuntu-latest` with `avrea-ubuntu-24.04`:

```yaml title=".avrea/workflows/test.yml"
jobs:
  test:
    runs-on: avrea-ubuntu-24.04
    steps:
      - uses: actions/checkout@v7
      - run: ./scripts/test.sh
```

Choose a runner image and size from [Runners & Pricing](/runners/).

Review references to the old workflow location:

- Update `paths` and `paths-ignore` filters so editing `.avrea/workflows/`
  triggers the intended tests.
- Update scripts or tooling that explicitly read `.github/workflows/` files.
- If you use `.github/workflows/actions.lock`, keep it at that path. Avrea CI
  reads the same file. Add the copied `.avrea/workflows/...` paths to its
  `workflows` map so their action pins apply; keep the original workflow
  entries while both copies run.
- Keep local action paths such as `./.github/actions/setup` if the action
  remains there. Copying workflows does not require moving local actions.
- Update local reusable workflow calls to the copied path, for example
  `uses: ./.avrea/workflows/shared.yml`. Reusable workflows are supported for
  push runs; review [source access and call limits](/avrea-ci/workflows/#reusable-workflows).

For example, include the new workflow path in a filtered build:

```yaml
on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - '.avrea/workflows/test.yml'
  pull_request:
    paths:
      - 'src/**'
      - '.avrea/workflows/test.yml'
```

## 4. Review credentials and integrations

GitHub secrets and variables are not copied with the YAML. Create the needed
values in Avrea and scope them to the repository and the new workflow path.
See [Secrets and variables](/avrea-ci/secrets/).

Keep credential-dependent pull request work on GitHub Actions, or move it to
an Avrea CI push or manual workflow. Review
[managed configuration eligibility](/avrea-ci/workflows/#managed-configuration)
when choosing the trigger.

Avrea CI does not supply a general-purpose GitHub `GITHUB_TOKEN` or GitHub
Actions OIDC identity. Review actions that publish releases, push commits,
comment on pull requests, or authenticate to a cloud provider. A `permissions`
block alone does not give those actions credentials.

Review artifact steps as well. Use [Avrea workflow artifacts](/workflow-artifacts/)
when the documented action release prerequisites are met. Do not assume GitHub
artifact uploads, existing GitHub artifacts, or numeric GitHub run IDs carry
over to Avrea CI.

## 5. Compare runs

Commit the copied workflow and push it to a branch allowed by its trigger.
Open the repository's runs in the Avrea console and select **Avrea CI**.
Compare the tested commit, job results, logs, outputs, and artifacts with your
GitHub Actions workflow. Test the triggers you intend to use, including a
pull request if applicable.

For manual execution, first commit the workflow with `workflow_dispatch` to
the repository's default branch. It must also declare that trigger at the
branch or tag you select. See [manual runs](/avrea-ci/workflows/#manual-runs).

<Aside type="caution" title="Avoid duplicate deployments">
Both copies can run on the same event. Start with build and test jobs; keep
deployment and publishing enabled in only one system during the comparison.
Concurrency groups in GitHub Actions and Avrea CI do not coordinate with each
other, even when their names match.
</Aside>

## 6. Switch required checks

After Avrea CI has completed successfully on the events you use, select its
actual published checks in your GitHub branch protection rules or rulesets.
Verify that a failing Avrea CI job blocks merging as intended.

Then disable or remove only the corresponding `.github/workflows/*.yml` or
`*.yaml` workflow files. Keep `.github/workflows/actions.lock` if present;
do not delete the whole directory. Remove the old required checks as part of
the same cutover, so GitHub does not wait for workflows you no longer run.
Keep any workflows that still need GitHub Actions features.

For later changes, edit the files in `.avrea/workflows/` and review the
resulting Avrea CI runs.