# Organization runners

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

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](/runners/).

## 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](/github-permissions/#organization-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](mailto:support@avrea.com).

<Steps>

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.

   <Aside title="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](https://docs.github.com/en/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner).
   The card in step 2 appears once the install is approved.
   </Aside>

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.

</Steps>

<Aside title="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.
</Aside>

### 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](mailto:support@avrea.com) with your organization name.