Self-Hosted Runners

Use the runs-on frontmatter field to target a self-hosted runner instead of the default ubuntu-latest.

For these reasons, a non-sudo mode is not supported, including ARC configurations with allowPrivilegeEscalation: false.

runs-on formats

String — single runner label:

---
on: issues
runs-on: self-hosted
---

Array — runner must have all listed labels (logical AND):

---
on: issues
runs-on: [self-hosted, linux, x64]
---

Object — named runner group, optionally filtered by labels:

---
on: issues
runs-on:
  group: my-runner-group
  labels: [linux, x64]
---

runs-on must be set in each workflow — it is not merged from imports. Other settings like network and tools can be shared:

---
network:
  allowed:
    - defaults
    - private-registry.example.com
tools:
  bash: {}
---

---
on: issues
imports:
  - shared/runner-config.md
runs-on: [self-hosted, linux, x64]
---

Triage this issue.

Configuring the detection job runner

When threat detection is enabled, the detection job runs on the agent job’s runner by default. Override it with safe-outputs.threat-detection.runs-on:

---
on: issues
runs-on: [self-hosted, linux, x64]
safe-outputs:
  create-issue: {}
  threat-detection:
    runs-on: ubuntu-latest
---

This is useful when your self-hosted runner lacks outbound internet access for AI detection, or when you want to run the detection job on a cheaper runner.

Configuring the framework job runner

Framework jobs — activation, pre-activation, safe-outputs, unlock, APM, update_cache_memory, and push_repo_memory — default to ubuntu-slim. Use runs-on-slim: to override all of them at once:

---
on: issues
runs-on: [self-hosted, linux, x64]
runs-on-slim: self-hosted
safe-outputs:
  create-issue: {}
---

Frontmatter — runs-on and runs-on-slim syntax reference
Imports — importable fields and merge semantics
Threat Detection — detection job configuration
Network Access — configuring outbound network permissions
Sandbox — container and Docker requirements

Self-Hosted Runners

runs-on formats

Sharing configuration via imports

Configuring the detection job runner

Configuring the framework job runner

Related documentation