Organization runners

Avrea can register runners for a GitHub organization in two ways:

• Organization runners. One Avrea App installed on your GitHub organization registers runners in a runner group of that organization. Any repository you give the App access to can use them.
• Repository runners. The Avrea App registers a runner on each repository separately. This is how installations on personal accounts work, and how organizations set up before organization runners were available.

Organization runners are the default for new GitHub organizations. Your workflows are the same on both: a job runs on Avrea when its runs-on names an Avrea label, as described in Runners & Pricing.

New organizations

If you installed Avrea from the console and chose GitHub organization, you already have organization runners. The App requests the organization Self-hosted runners permission instead of repository Administration; see GitHub App permissions.

Switching an existing installation

An installation that registers repository runners can move to organization runners from the Avrea console. The switch pauses new job starts once, for as long as the jobs running at that moment take; running jobs are not affected.

Before you start

• Who can do it. Adding the installation needs an Admin of your Avrea organization. A GitHub organization owner can install directly; anyone else can only request the install (see the note in step 1). Activating needs permission to manage installations, which Admins have. Start from the Avrea organization that owns the current installation; an install started from another Avrea organization is refused as already connected elsewhere.
• Labels. Jobs on organization runners must list only Avrea labels in runs-on. A job whose runs-on also names any other label, such as self-hosted, linux, x64 or a label of your own, is cancelled before it starts: Avrea marks the commit with a failed check named Avrea runner labels cannot be combined that names the job, and comments on the pull request if there is one. On repository runners such lists worked because the runner was registered with every label the job asked for, so check your workflows first.
• Repository access. After the switch, the repositories Avrea runs for are the ones the Organization App has access to. Give it the same repositories as your current installation. A repository you leave out disappears from Avrea, and its queued jobs are cancelled, until you add it on GitHub; its history is kept.
• The runner group. Avrea creates a runner group named Avrea … in your GitHub organization and keeps its repository list in step with the App's access. Do not rename the group, change its visibility or edit its repositories by hand; manage access through the App.

If Add new in your Avrea settings offers no GitHub organization choice, organization runners are not available yet. Contact support@avrea.com.

1. Install the Organization App. In the Avrea console, open Organization settings → Installations, click Add new and choose GitHub organization. On GitHub, select your organization and give the App access to the same repositories your current installation has. When GitHub sends you back, a dialog confirms the App is installed but not yet active. If it says GitHub is still confirming the installation, wait a few minutes.

   Not a GitHub org owner?

   If your GitHub organization requires owner approval for App installations, GitHub records the install as a pending request and notifies the owners; Avrea shows nothing until it is approved. Ask an owner to approve it from the organization's installed apps settings. The card in step 2 appears once the install is approved.

2. Find the card. The settings page shows Organization runners for your organization are ready. Nothing has changed for your jobs yet: they still run on repository runners.

3. Activate. Click Activate organization runners. Avrea pauses new job starts for this installation, lets the running jobs finish, switches runner registration to your organization, re-reads the organization's repositories from GitHub and resumes. The card shows how many runners it is still waiting for. Jobs that arrive during the pause wait on GitHub for a runner and start as soon as the switch completes; none of them fail.

4. Uninstall the previous App. Once the card says organization runners are active, it links to your previous Avrea App on GitHub, which is now unused. Uninstall it from there. Do this only after the switch has completed: removing it first stops all job starts until you click Activate.

How long is the pause?

As long as the longest job running when you click Activate, plus up to a minute or two for runner cleanup and for Avrea to re-read your organization's repositories from GitHub. Organizations with many repositories take longer.

After the switch

• Repository access is managed on the Organization App in your GitHub organization's installed apps settings. Avrea follows it automatically.
• Cache settings, usage history and billing are unchanged.
• If the card reports that scheduling is paused for another reason, or the activation does not complete, contact support@avrea.com with your organization name.