Add documentation page on self-hosted runners configuration#17986
Add documentation page on self-hosted runners configuration#17986
Conversation
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a new guide page documenting how to configure agentic workflows to run on self-hosted GitHub Actions runners, and wires it into the docs sidebar navigation.
Changes:
- Added a new “Self-Hosted Runners” guide covering
runs-onformats, requirements, and related references. - Added a “Self-Hosted Runners” entry to the Guides sidebar in the Astro docs config.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/src/content/docs/guides/self-hosted-runners.md | New documentation page for self-hosted runner configuration and examples. |
| docs/astro.config.mjs | Adds the new guide page to the Guides sidebar navigation. |
Comments suppressed due to low confidence (1)
docs/src/content/docs/guides/self-hosted-runners.md:88
- The text here describes merge/precedence behavior for an imported top-level
runs-on. Since top-levelruns-onisn’t merged from markdown imports today, this precedence/override example is misleading. Please update this section to match what imports actually merge (e.g., if the intent is to share runner config, documentsafe-outputs.runs-onsharing instead).
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
---
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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: |
There was a problem hiding this comment.
The runs-on label array semantics described here are incorrect. In GitHub Actions, runs-on: [self-hosted, linux, x64] requires a runner that has all listed labels (AND), not “any label in the list”. Please update the explanation accordingly (and avoid implying label arrays provide fallback behavior).
| **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). This is useful for targeting pools that are constrained by multiple labels, such as OS and architecture: |
There was a problem hiding this comment.
Fixed in cdece02. The label array description now reads: "requires a runner that has all of the listed labels (logical AND)."
| 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] |
There was a problem hiding this comment.
This section says you can define top-level runs-on once in a shared .md file and import it. The markdown import processor does not extract/merge a top-level runs-on field (it merges things like tools, network, permissions, safe-outputs, etc., but not runs-on; see pkg/parser/import_processor.go where there is no runs-on extraction). As written, the example import won’t affect the workflow runner selection.
This issue also appears on line 85 of the same file.
| 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 also share other configuration like `network`, `permissions`, or `tools`. You can define those shared settings once in a shared file and import it into each workflow. Note that `runs-on` itself must still 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 | |
| --- | |
| network: private-vpc | |
| permissions: | |
| contents: read |
There was a problem hiding this comment.
Fixed in cdece02. The section now correctly states that runs-on is not merged from imports, and the example shows sharing network and tools configuration instead. The workflow example sets runs-on directly.
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
|
Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details. Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
|
@copilot unbloat it (see unblaot-docs.md) |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Done in eb53704. Removed the Prerequisites and Runner Requirements sections (redundant with the note at the top), condensed descriptions, and stripped boilerplate from code examples — ~44% line reduction (107 → 60 lines). Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
|
@copilot make sure there is a section on configurion the detection job |
Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Added in 059ff73. The new "Configuring the detection job runner" section explains that the detection job inherits the agent job's runner by default, and shows how to override it with Warning Firewall rules blocked me from connecting to one or more addresses (expand for details)I tried to connect to the following addresses, but was blocked by firewall rules:
If you need me to access, download, or install something from one of these locations, you can either:
|
pelikhan
deleted the
copilot/add-documentation-page-self-hosted-runners
branch
Adds a new guide page explaining how to configure self-hosted runners in agentic workflows, covering all
runs-onformats, shared configuration patterns, and detection job runner overrides.Changes
docs/src/content/docs/guides/self-hosted-runners.mdruns-onstring, array (logical AND semantics), and group/labels object formatsruns-onis not merged from imports; shows how to sharenetwork/toolsconfig via a shared import file insteadsafe-outputs.threat-detection.runs-on, including the fallback behavior (inherits agent job runner by default)astro.config.mjsValidation
make build-docspasses — all internal links valid🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.