Migrate to Avrea CI
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
Section titled “1. Connect and enable the repository”Install the Avrea GitHub App with access to your repository. Contact support@avrea.com to have Avrea CI and repository mirroring enabled for that repository.
Review compatibility and limits before copying workflows. Keep workflows that need unsupported features on GitHub Actions until you have adapted them.
2. Copy your workflow files
Section titled “2. Copy your workflow files”Use the same filenames under .avrea/workflows/:
.github/workflows/test.yml → .avrea/workflows/test.yml.github/workflows/build.yaml → .avrea/workflows/build.yamlFrom your repository root, copy one workflow to start:
mkdir -p .avrea/workflowscp -i .github/workflows/test.yml .avrea/workflows/test.ymlOr copy all workflow files for review:
mkdir -p .avrea/workflowsfind .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
Section titled “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:
jobs: test: runs-on: avrea-ubuntu-24.04 steps: - uses: actions/checkout@v7 - run: ./scripts/test.shChoose a runner image and size from Runners & Pricing.
Review references to the old workflow location:
- Update
pathsandpaths-ignorefilters 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 itsworkflowsmap so their action pins apply; keep the original workflow entries while both copies run. - Keep local action paths such as
./.github/actions/setupif 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.
For example, include the new workflow path in a filtered build:
on: push: branches: [main] paths: - 'src/**' - '.avrea/workflows/test.yml' pull_request: paths: - 'src/**' - '.avrea/workflows/test.yml'4. Review credentials and integrations
Section titled “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.
Keep credential-dependent pull request work on GitHub Actions, or move it to an Avrea CI push or manual workflow. Review managed configuration eligibility 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 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
Section titled “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.
6. Switch required checks
Section titled “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.