Runner Setup

This page covers how to install, configure, and run self-hosted runners for Copia Actions. Runners are the machines that execute your workflow jobs. You can install a runner as a standalone binary, in a Docker container, or via docker-compose.

Requirements

The runner supports two execution modes:

• Host mode (recommended): Jobs run directly on the runner machine. Docker is not required, but you are responsible for ensuring the correct tools and dependencies are available.

• Docker mode: Jobs run in isolated Docker containers. You must have Docker Engine installed and the Docker daemon running. Other OCI-compatible container engines should work but are untested.

Docker mode is recommended because it provides better isolation, reproducibility, and security.

Installation Methods

Install from Binary

Navigate to your organization runner settings page or your repository's runner settings page and follow the on-screen instructions to download, configure, and start the actions runner on your system.

---

macOS (launchd)

Create /Library/LaunchDaemons/com.copia.act_runner.plist:

{% code title="com.copia.act_runner.plist" %}

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.copia.act_runner</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/local/bin/act_runner</string>
    <string>daemon</string>
    <string>--config</string>
    <string>/etc/act_runner/config.yaml</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>WorkingDirectory</key>
  <string>/var/lib/act_runner</string>
  <key>StandardOutPath</key>
  <string>/var/lib/act_runner/act_runner.log</string>
  <key>StandardErrorPath</key>
  <string>/var/lib/act_runner/act_runner.err</string>
  <key>EnvironmentVariables</key>
  <dict>
    <key>PATH</key>
    <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>HOME</key>
    <string>/var/lib/act_runner</string>
  </dict>
</dict>
</plist>

{% endcode %}

Load the service:

sudo launchctl load /Library/LaunchDaemons/com.copia.act_runner.plist

### Windows

Windows service installation instructions are not included here. Options include NSSM (Non-Sucking Service Manager) or a native Windows Service wrapper.

## Labels

Labels determine which jobs a runner can accept and how those jobs are executed. When a workflow specifies `runs-on: ubuntu-latest`, Copia routes the job to a runner that has the `ubuntu-latest` label.

The default labels are:

ubuntu-latest:docker://node:16-bullseye ubuntu-22.04:docker://node:16-bullseye ubuntu-20.04:docker://node:16-bullseye ubuntu-18.04:docker://node:16-buster

### Label Format

Labels follow the format `label_name:schema://image`:

| Label | Meaning |
|---|---|
| `ubuntu-latest:docker://node:16-bullseye` | Run in Docker using the `node:16-bullseye` image |
| `linux_amd64:host` | Run directly on the host machine |
| `my-custom-env:docker://my-org/my-image:latest` | Run in Docker using a custom image |

If the schema is omitted (e.g., just `ubuntu-latest`), it defaults to `host`.

### Customizing Labels

You can specify custom labels during registration with the `--labels` flag, or modify the `runners.labels` section in your runner's `config.yaml` file. Restart the runner after changing labels.

Example registration with a custom label:

<div data-gb-custom-block data-tag="code"></div>

./act_runner register \
  --no-interactive \
  --instance https://app.copia.io \
  --token <token> \
  --labels "plc-builder:docker://ubuntu:22.04"

Ephemeral Runners

Ephemeral runners are a security hardening option. An ephemeral runner registers, executes a single job, and then terminates. Its credentials are revoked as soon as a job is assigned, preventing it from polling for additional jobs.

This is useful for environments where runners are spun up dynamically (for example, in spot VMs or short-lived containers).

To register an ephemeral runner:

./act_runner register
--no-interactive
--ephemeral
--instance https://app.copia.io
--token <your_registration_token>
--name <runner_name>

Or with Docker:

<div data-gb-custom-block data-tag="code"></div>

docker run \
  -e GITEA_INSTANCE_URL=https://app.copia.io \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<your_registration_token> \
  -e GITEA_RUNNER_EPHEMERAL=1 \
  -e GITEA_RUNNER_NAME=<runner_name> \
  --name copia_runner \
  -d docker.io/gitea/act_runner:latest

The runner must be re-registered each time you want it to accept a new job. You can automate this using the workflow_job webhook to spin up and register a fresh runner whenever a job is queued.

Note for Self-Hosted customers: Replace https://app.copia.io with your instance URL in all commands above.