Act Runner on StartOS

Upstream docs: https://docs.gitea.com/usage/actions/act-runner

Everything not listed in this document should behave the same as upstream Act Runner. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.

Act Runner is a lightweight CI/CD runner for Gitea Actions. This StartOS package connects to a Gitea instance and executes workflow jobs.

---

Table of Contents

• Image and Container Runtime
• Volume and Data Layout
• Installation and First-Run Flow
• Configuration Management
• Actions (StartOS UI)
• Health Checks
• Limitations and Differences
• What Is Unchanged from Upstream
• Contributing
• Quick Reference for AI Consumers

---

Image and Container Runtime

Property	Value
Image source	Custom Dockerfile (Alpine 3.21 + act_runner)
Architectures	x86_64, aarch64
Entrypoint	act_runner

Volume and Data Layout

Volume	Mount Point	Contents
main	/data	Runner registration (.runner), config (config.yaml), cache

Installation and First-Run Flow

1. Install the package.
2. Run the Register Runner action with your Gitea instance URL and registration token.
3. Start the service.

The runner will not start until registered. Before registration, the service displays a "not running" health status.

Configuration Management

StartOS-Managed	Upstream-Managed
Instance URL, runner name, labels	None (no upstream UI)
config.yaml (generated on registration)	--

The config.yaml is generated during registration with sensible defaults. To change settings, re-run the Register Runner action.

Actions (StartOS UI)

Register Runner

• Purpose: Register this runner with a Gitea instance
• Availability: Only when stopped
• Inputs: Instance URL, registration token, runner name, labels
• Outputs: Success/failure message

Get Registration Status

• Purpose: Check if the runner is registered and show connection details
• Availability: Any status
• Outputs: Registration status, instance URL, runner name

Health Checks

• Method: Registration status check
• Success: "Act Runner is running and connected"
• Not registered: "Act Runner is not running"

Limitations and Differences

1. Host mode only -- This package runs workflow steps directly on the runner's filesystem rather than in isolated Docker containers. The StartOS container environment does not support nested containerization (Docker-in-Docker), so the docker label scheme is unavailable. The default label is ubuntu-latest:host.

2. No workflow isolation -- Because workflows run in host mode, there is no container boundary between workflow runs. Workflows share the same filesystem and can see artifacts left by previous runs. Only use this runner with trusted repositories.

3. Limited runtime environment -- The runner's container is a minimal Alpine Linux environment. Workflows that depend on Ubuntu-specific packages, systemd, or other OS-level features may need to install dependencies as part of their workflow steps.

4. No Docker commands in workflows -- Workflow steps cannot use docker build, docker run, or other Docker commands since no Docker daemon is available.

What Is Unchanged from Upstream

• Gitea Actions workflow syntax and compatibility
• Runner registration protocol
• Job fetching and reporting
• Cache functionality
• Timeout and capacity settings
• Log levels and output

Contributing

See CONTRIBUTING.md for build instructions.

---

Quick Reference for AI Consumers

package_id: act-runner
upstream_version: latest
image: custom Dockerfile (Alpine 3.21)
architectures: [x86_64, aarch64]
volumes:
  main: /data
ports: {}
dependencies: []
startos_managed_env_vars: []
actions:
  - register-runner
  - get-registration-status
limitations:
  - Host mode only (no Docker container isolation)
  - No Docker daemon available in workflows
  - Minimal Alpine runtime environment