Skip to main content

Prerequisites

The following operating systems are supported for the self-hosted runner.

Linux

  • Ubuntu 20.04 or later
  • Debian 11 or later

MacOS

  • macOS 15 (Sequoia) or later on Apple silicon (arm64). Intel-based Macs are not supported.

The following processor architectures are supported for operating systems.

  • x64 Linux only
  • arm64 macOS only

To install and execute runner, you will need to have root access. Being able to run sudo (sudoer) is sufficient for runner operations.

Also you need to have the following tools installed on your system:

  • curl
  • unzip

These tools are already installed on most operating systems or can be got from default package managers.

Minimum hardware requirements for self-hosted runner can be:

  • 100GB or more free disk space
  • 2 or more cores CPU (x64 for Linux, arm64 for macOS)
  • 8 gigabytes (GB) or more RAM

Minimum required disk space is for the android platform tools. For iOS builds, see the disk space requirements of the macOS VM image.

info

For linux installations, you can also prefer docker container for supported distributions. You can install linux package of self-hosted runner on a running docker container same as bare-metals.

But you must select a docker image with systemd support enabled.

You can either install and configure systemd on docker by yourself, or choose from preconfigured images.

See here for more detailed information about systemd in a container.

Or, as a quick alternative, you can use docker images from here for ubuntu containers.

Let's assume, you selected ready-to-use ubuntu:20.04 image from there.

First you should start container with command below.

docker run -d --name systemd-ubuntu --privileged -v /sys/fs/cgroup:/sys/fs/cgroup:ro jrei/systemd-ubuntu:20.04

Log in to running container with bash, interactively.

docker exec -it systemd-ubuntu /bin/bash

From now on, you will follow same installation steps seen below as other environments.

caution

macOS VM​

Appcircle provides a ready-to-use macOS VM image that comes with both iOS (Xcode) and android build tools preinstalled, so it can run both iOS and android builds. It can be run on macOS Sequoia or Tahoe arm64 hosts according to the guest macOS version.

Installing Xcode through the runner is no longer supported for Xcode 16 and later, so iOS builds require the macOS VM image.

See details in here.

Installation​

Adding a self-hosted runner requires that you download, register and configure Appcircle runner in your environment.

1. Download​

Download the latest self-hosted runner package.

curl -O -L https://cdn.appcircle.io/self-hosted/runner/appcircle-runner-osx-arm64-1.8.5.zip

Extract self-hosted runner package.

unzip -o -u appcircle-runner-osx-arm64-1.8.5.zip

Change directory into extracted appcircle-runner folder for following steps.

cd appcircle-runner
caution

By default, the self-hosted runner package is bundled with configuration for the Appcircle-hosted cloud.

🎗 If you're planning to use runner with the self-hosted server, you must change ASPNETCORE_BASE_API_URL and ASPNETCORE_REDIS_STREAM_ENDPOINT values in appsettings.json configuration file before going on.

For Docker installations, please refer to the details here for sample configuration changes.

For Podman installations, please refer to the details here for sample configuration changes.

For Kubernetes installations, please refer to the details here for sample configuration changes.

2. Register​

Go to your organization's integration settings and generate runner access token.

Screenshot

Using generated token, register self-hosted runner to your organization with desired name and pool.

./ac-runner register -t ${Access Token} -n ${Runner Name} -p ${Runner Pool}

Runner name is the text that you identify your self-hosted runner in your organization. You can use any suitable text for runner naming according to your requirements. You will find registered self-hosted runner in "Self-hosted Runners" list with the given name.

Runner pool is the text which identifies the runner pool in your organization. You can use any suitable text for pool naming according to your requirements. You will use given pool name at build profile settings and also see registered self-hosted runner in "Self-hosted Runners" list with the given pool name.

For example, below command is registering runner named "runner1" with pool named "Arm64_pool" to specified organization with using generated runner access token.

./ac-runner register -t aat_XVY27uHw7W1GA_cw5Vut0p_WOzHeYeJ2ZkTbqAVE3GX -n runner1 -p Arm64_pool

For more details on runner and pool, see Manage Self-hosted Pools and Manage Self-hosted Runners in docs.

info

Access token is required only for registration process and it can be used for any self-hosted runner, many times until revoked.

Revoking access token itself is not affecting already registered runners. You can't register new self-hosted runners to organization with revoked token anymore.

Only one valid access token can be used actively for an organization. There is no hard-limit on token generation and revoke. Acccording to your security requirements, you can revoke and generate new access token anytime you want.

Once you complete this step, you will see new added runner at "Build > Self-hosted Runners" list.

It's enabled by default but its state should be Offline by now.

3. Configure​

caution

By default, the self-hosted runner package is bundled with configuration for the Appcircle-hosted cloud.

🎗 If you're planning to use runner with the self-hosted server, you must change ASPNETCORE_BASE_API_URL and ASPNETCORE_REDIS_STREAM_ENDPOINT values in appsettings.json configuration file before going on.

For Docker installations, please refer to the details here for sample configuration changes.

For Podman installations, please refer to the details here for sample configuration changes.

For Kubernetes installations, please refer to the details here for sample configuration changes.

You need to install some workflow required build tools once before executing any build pipeline.

Xcode 16 and later

Installing Xcode through the runner is no longer supported for Xcode 16 and later. The -o ios platform option and the -x Xcode argument only cover Xcode 15.4 and earlier, which can't be used to submit apps to the App Store.

For iOS builds, use the macOS VM image instead. It comes with both iOS (Xcode) and android build tools preinstalled, so it can run both iOS and android builds without installing any build tools on the runner.

Install the android platform tools with the command below.

./ac-runner install -o android

Self-Signed Certificates​

If you're using self-signed certificates, you need to follow the below document to add your certificates to runners.

File Icon

Self-Signed Certificates

4. Run Service​

Install and start self-hosted runner service.

./ac-runner service -c install

Once you complete this step, its state should be seen as Online in "Self-hosted Runners" list.

info

You can install and run only one instance of self-hosted runner on a physical machine.

If you need concurrency or multiple instances of self-hosted runner but don't have multiple bare-metals, then you should use virtualization infrastructure.

You can install multiple VMs on a single bare-metal and deploy self-hosted runner to each VM seperately.

:::

tip

You can also add or change platform tools after start of runner service.

The platform argument (-o) doesn't work as an append strategy; your latest platform argument will be the runner's final platform.

Install command used for runner configuration, both adds tools to your system and makes some configurations for them. In order to activate changes and updates completely, you should restart runner service after configuration is done successfully.

./ac-runner service -c restart

Restarting runner service will first stop service and start it again.

See here for more details about runner service operations.

5. Build App​

Congratulations, now your runner is waiting for build jobs. In order to use your self-hosted runner pool;

  • Find your app's build profile in "Build Profiles"
  • Click on "Configurations" to open branch config details
  • Select your runner's pool from "Config" tab
  • Check also other settings for your runner capabilities
  • Save settings and pool configuration
  • Start Build 🎉