From d3c7b017dc1eaa52c38dcb481005d2f93ea58dcf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:00:06 +0000 Subject: [PATCH 1/5] Initial plan From 497578e4051d2bfeab45b08afbfbd8b5dbc09ecf Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Feb 2026 22:07:01 +0000 Subject: [PATCH 2/5] docs: add self-hosted runners guide with shared config documentation Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- docs/astro.config.mjs | 1 + .../docs/guides/self-hosted-runners.md | 117 ++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 docs/src/content/docs/guides/self-hosted-runners.md diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 8e3f1a261f..4019f5c5bb 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -181,6 +181,7 @@ export default defineConfig({ { label: 'Ephemerals', link: '/guides/ephemerals/' }, { label: 'GitHub Actions Primer', link: '/guides/github-actions-primer/' }, { label: 'Reusing Workflows', link: '/guides/packaging-imports/' }, + { label: 'Self-Hosted Runners', link: '/guides/self-hosted-runners/' }, { label: 'Using MCPs', link: '/guides/mcps/' }, { label: 'Web Search', link: '/guides/web-search/' }, ], diff --git a/docs/src/content/docs/guides/self-hosted-runners.md b/docs/src/content/docs/guides/self-hosted-runners.md new file mode 100644 index 0000000000..bdc529594c --- /dev/null +++ b/docs/src/content/docs/guides/self-hosted-runners.md @@ -0,0 +1,117 @@ +--- +title: Self-Hosted Runners +description: How to configure agentic workflows to run on self-hosted runners using the runs-on field, and how to share runner configuration across workflows with a shared import file. +sidebar: + order: 5 +--- + +By default, agentic workflows run on GitHub-hosted `ubuntu-latest` runners. You can change this using the `runs-on` frontmatter field to target self-hosted runners — for example, to access private networks, use specialized hardware, or manage your own runner pools. + +## Prerequisites + +Your self-hosted runner must run Linux. macOS and Windows runners are not supported because agentic workflows require container support for the [sandbox](/gh-aw/reference/sandbox/). + +## Configuring runs-on + +The `runs-on` field accepts three formats. + +**Simple label** — the most common form, matching any runner that has the given label: + +```aw +--- +on: issues +runs-on: self-hosted +--- + +Triage this issue. +``` + +**Label array** — GitHub Actions picks the first available runner that matches any label in the list. Useful for high-availability pools with multiple runner groups: + +```aw +--- +on: issues +runs-on: [self-hosted, linux, x64] +--- + +Triage this issue. +``` + +**Group and labels object** — targets a named runner group, optionally filtered by labels. Useful when your organization uses runner groups to organize pools by team or environment: + +```aw +--- +on: issues +runs-on: + group: my-runner-group + labels: [linux, x64] +--- + +Triage this issue. +``` + +> [!NOTE] +> The `runs-on` field only applies to the main agent job. Custom jobs defined in `jobs:` configure their own `runs-on` field independently. + +## Sharing Runner Configuration with Imports + +When multiple workflows share the same runner requirements, define the `runs-on` configuration once in a shared file and import it. This avoids repeating runner labels across every workflow. + +Create a shared configuration file, for example `.github/workflows/shared/runner-config.md`: + +```aw +--- +runs-on: [self-hosted, linux, x64] +--- +``` + +> [!NOTE] +> Shared files without an `on:` field are treated as shared workflow components and are not compiled into GitHub Actions workflows on their own. + +Then import this file in any workflow that needs it: + +```aw +--- +on: issues +imports: + - shared/runner-config.md +permissions: + issues: write +--- + +Triage this issue and assign appropriate labels. +``` + +The compiler merges the `runs-on` field from the imported file into the workflow. The main workflow's `runs-on` always takes precedence over imported values — so you can import a default runner and override it per-workflow when needed: + +```aw +--- +on: issues +imports: + - shared/runner-config.md +runs-on: [self-hosted, linux, arm64] # overrides the imported value +permissions: + issues: write +--- + +Triage this issue on the ARM runner. +``` + +## Runner Requirements + +Self-hosted runners must meet the following requirements for agentic workflows: + +- **Linux only** — Docker container support is required for the agent sandbox +- **Docker** — the runner must have Docker installed and running +- **Network access** — the runner needs outbound internet access unless you configure a fully air-gapped setup with appropriate [network permissions](/gh-aw/reference/network/) + +> [!WARNING] +> macOS (`macos-*`) and Windows (`windows-*`) runners are not supported. Agentic workflows use Docker containers for the agent execution sandbox, which requires Linux. + +## Related Documentation + +- [Frontmatter Reference](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-timeout-minutes) — complete reference for `runs-on` and other run configuration fields +- [Reusing Workflows](/gh-aw/guides/packaging-imports/) — how to create and use shared import files +- [Imports Reference](/gh-aw/reference/imports/) — import merge semantics and path formats +- [Sandbox](/gh-aw/reference/sandbox/) — how the agent execution sandbox works +- [Network Access](/gh-aw/reference/network/) — configuring network permissions for workflows From cdece02abbaa738792bcd9f096f8167584687259 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Feb 2026 23:43:14 +0000 Subject: [PATCH 3/5] docs: fix label array semantics and rewrite shared config section Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../docs/guides/self-hosted-runners.md | 39 +++++++------------ 1 file changed, 14 insertions(+), 25 deletions(-) diff --git a/docs/src/content/docs/guides/self-hosted-runners.md b/docs/src/content/docs/guides/self-hosted-runners.md index bdc529594c..0b70cd4565 100644 --- a/docs/src/content/docs/guides/self-hosted-runners.md +++ b/docs/src/content/docs/guides/self-hosted-runners.md @@ -26,7 +26,7 @@ runs-on: self-hosted Triage this issue. ``` -**Label array** — GitHub Actions picks the first available runner that matches any label in the list. Useful for high-availability pools with multiple runner groups: +**Label array** — requires a runner that has *all* of the listed labels (logical AND). Useful for targeting pools constrained by multiple labels, such as OS and architecture: ```aw --- @@ -53,48 +53,37 @@ Triage this issue. > [!NOTE] > The `runs-on` field only applies to the main agent job. Custom jobs defined in `jobs:` configure their own `runs-on` field independently. -## Sharing Runner Configuration with Imports +## Sharing Configuration with Imports -When multiple workflows share the same runner requirements, define the `runs-on` configuration once in a shared file and import it. This avoids repeating runner labels across every workflow. - -Create a shared configuration file, for example `.github/workflows/shared/runner-config.md`: - -```aw ---- -runs-on: [self-hosted, linux, x64] ---- -``` +When multiple workflows target the same self-hosted runners, they often share other configuration such as `network`, `tools`, or `safe-outputs`. You can define those shared settings once in a shared file and import it into each workflow. > [!NOTE] -> Shared files without an `on:` field are treated as shared workflow components and are not compiled into GitHub Actions workflows on their own. +> `runs-on` itself must be specified in every workflow file — it is not merged from imports. -Then import this file in any workflow that needs it: +Create a shared configuration file, for example `.github/workflows/shared/runner-config.md`: ```aw --- -on: issues -imports: - - shared/runner-config.md -permissions: - issues: write +network: + allowed: + - defaults + - private-registry.example.com +tools: + bash: {} --- - -Triage this issue and assign appropriate labels. ``` -The compiler merges the `runs-on` field from the imported file into the workflow. The main workflow's `runs-on` always takes precedence over imported values — so you can import a default runner and override it per-workflow when needed: +Then import this file in any workflow that needs it, and set `runs-on` directly: ```aw --- on: issues imports: - shared/runner-config.md -runs-on: [self-hosted, linux, arm64] # overrides the imported value -permissions: - issues: write +runs-on: [self-hosted, linux, x64] --- -Triage this issue on the ARM runner. +Triage this issue and assign appropriate labels. ``` ## Runner Requirements From eb53704d445f7f02e4df2f29855a1be43168ff3d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 23 Feb 2026 23:50:21 +0000 Subject: [PATCH 4/5] docs: unbloat self-hosted runners guide Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../docs/guides/self-hosted-runners.md | 67 +++++-------------- 1 file changed, 17 insertions(+), 50 deletions(-) diff --git a/docs/src/content/docs/guides/self-hosted-runners.md b/docs/src/content/docs/guides/self-hosted-runners.md index 0b70cd4565..3b19af3198 100644 --- a/docs/src/content/docs/guides/self-hosted-runners.md +++ b/docs/src/content/docs/guides/self-hosted-runners.md @@ -1,43 +1,34 @@ --- title: Self-Hosted Runners -description: How to configure agentic workflows to run on self-hosted runners using the runs-on field, and how to share runner configuration across workflows with a shared import file. -sidebar: - order: 5 +description: How to configure the runs-on field to target self-hosted runners in agentic workflows. --- -By default, agentic workflows run on GitHub-hosted `ubuntu-latest` runners. You can change this using the `runs-on` frontmatter field to target self-hosted runners — for example, to access private networks, use specialized hardware, or manage your own runner pools. +Use the `runs-on` frontmatter field to target a self-hosted runner instead of the default `ubuntu-latest`. -## Prerequisites - -Your self-hosted runner must run Linux. macOS and Windows runners are not supported because agentic workflows require container support for the [sandbox](/gh-aw/reference/sandbox/). - -## Configuring runs-on +> [!NOTE] +> Runners must be Linux with Docker support. macOS and Windows are not supported — agentic workflows require container jobs for the [sandbox](/gh-aw/reference/sandbox/). -The `runs-on` field accepts three formats. +## runs-on formats -**Simple label** — the most common form, matching any runner that has the given label: +**String** — single runner label: ```aw --- on: issues runs-on: self-hosted --- - -Triage this issue. ``` -**Label array** — requires a runner that has *all* of the listed labels (logical AND). Useful for targeting pools constrained by multiple labels, such as OS and architecture: +**Array** — runner must have *all* listed labels (logical AND): ```aw --- on: issues runs-on: [self-hosted, linux, x64] --- - -Triage this issue. ``` -**Group and labels object** — targets a named runner group, optionally filtered by labels. Useful when your organization uses runner groups to organize pools by team or environment: +**Object** — named runner group, optionally filtered by labels: ```aw --- @@ -46,23 +37,13 @@ runs-on: group: my-runner-group labels: [linux, x64] --- - -Triage this issue. ``` -> [!NOTE] -> The `runs-on` field only applies to the main agent job. Custom jobs defined in `jobs:` configure their own `runs-on` field independently. - -## Sharing Configuration with Imports +## Sharing configuration via imports -When multiple workflows target the same self-hosted runners, they often share other configuration such as `network`, `tools`, or `safe-outputs`. You can define those shared settings once in a shared file and import it into each workflow. +`runs-on` must be set in each workflow — it is not merged from imports. Other settings like `network` and `tools` can be shared: -> [!NOTE] -> `runs-on` itself must be specified in every workflow file — it is not merged from imports. - -Create a shared configuration file, for example `.github/workflows/shared/runner-config.md`: - -```aw +```aw title=".github/workflows/shared/runner-config.md" --- network: allowed: @@ -73,8 +54,6 @@ tools: --- ``` -Then import this file in any workflow that needs it, and set `runs-on` directly: - ```aw --- on: issues @@ -83,24 +62,12 @@ imports: runs-on: [self-hosted, linux, x64] --- -Triage this issue and assign appropriate labels. +Triage this issue. ``` -## Runner Requirements - -Self-hosted runners must meet the following requirements for agentic workflows: - -- **Linux only** — Docker container support is required for the agent sandbox -- **Docker** — the runner must have Docker installed and running -- **Network access** — the runner needs outbound internet access unless you configure a fully air-gapped setup with appropriate [network permissions](/gh-aw/reference/network/) - -> [!WARNING] -> macOS (`macos-*`) and Windows (`windows-*`) runners are not supported. Agentic workflows use Docker containers for the agent execution sandbox, which requires Linux. - -## Related Documentation +## Related documentation -- [Frontmatter Reference](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-timeout-minutes) — complete reference for `runs-on` and other run configuration fields -- [Reusing Workflows](/gh-aw/guides/packaging-imports/) — how to create and use shared import files -- [Imports Reference](/gh-aw/reference/imports/) — import merge semantics and path formats -- [Sandbox](/gh-aw/reference/sandbox/) — how the agent execution sandbox works -- [Network Access](/gh-aw/reference/network/) — configuring network permissions for workflows +- [Frontmatter](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-timeout-minutes) — `runs-on` syntax reference +- [Imports](/gh-aw/reference/imports/) — importable fields and merge semantics +- [Network Access](/gh-aw/reference/network/) — configuring outbound network permissions +- [Sandbox](/gh-aw/reference/sandbox/) — container and Docker requirements From 059ff73e684909fe34b35048186c4ad3fd993bf7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 24 Feb 2026 00:11:59 +0000 Subject: [PATCH 5/5] docs: add detection job runner configuration section Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .../content/docs/guides/self-hosted-runners.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/src/content/docs/guides/self-hosted-runners.md b/docs/src/content/docs/guides/self-hosted-runners.md index 3b19af3198..dbff97264b 100644 --- a/docs/src/content/docs/guides/self-hosted-runners.md +++ b/docs/src/content/docs/guides/self-hosted-runners.md @@ -65,9 +65,27 @@ runs-on: [self-hosted, linux, x64] Triage this issue. ``` +## Configuring the detection job runner + +When [threat detection](/gh-aw/reference/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`: + +```aw +--- +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. + ## Related documentation - [Frontmatter](/gh-aw/reference/frontmatter/#run-configuration-run-name-runs-on-timeout-minutes) — `runs-on` syntax reference - [Imports](/gh-aw/reference/imports/) — importable fields and merge semantics +- [Threat Detection](/gh-aw/reference/threat-detection/) — detection job configuration - [Network Access](/gh-aw/reference/network/) — configuring outbound network permissions - [Sandbox](/gh-aw/reference/sandbox/) — container and Docker requirements