Skip to content

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.

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.

Use the same filenames under .avrea/workflows/:

.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:

Terminal window
mkdir -p .avrea/workflows
cp -i .github/workflows/test.yml .avrea/workflows/test.yml

Or copy all workflow files for review:

Terminal window
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.

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:

.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.

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.

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'

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.

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.

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.