diff --git a/.github/aw/agent-runtime-instructions.md b/.github/aw/agent-runtime-instructions.md index 117e3ec5b07..518b5239994 100644 --- a/.github/aw/agent-runtime-instructions.md +++ b/.github/aw/agent-runtime-instructions.md @@ -48,7 +48,9 @@ Use these instructions when creating or updating workflows that mention Docker, ## Cloud Hypervisor guidance (preview) - Preview scope is narrow: GitHub-hosted runners only, Ubuntu Linux x86_64 only, and `/dev/kvm` must be present. -- The compiler emits host preflight and release-asset provisioning steps that download and checksum-verify the pinned Cloud Hypervisor binary, kernel, rootfs, and supervisor from the `gh-aw-firewall` release before AWF starts. +- The compiler emits host preflight and release-asset provisioning steps that download and checksum-verify the pinned Cloud Hypervisor binary, `virtiofsd`, kernel, rootfs, and supervisor from the `gh-aw-firewall` release before AWF starts, and grants only the runner user scoped read/write access to `/dev/kvm`. +- AWF launches with the host privileges required to create the VM but keeps strict network isolation; the guest defaults to 2 vCPUs and 4096 MiB, and its trusted topology attachment is limited to the MCP gateway on TCP 8080 (no CLI proxy). +- Not supported under Cloud Hypervisor: `tools.github.mode: gh-proxy`, the `integrity-reactions` feature, `sandbox.agent.legacy-security: enable`, `sandbox.agent.allow-host-ports`, and `enclaves:` configuration. - Do not recommend this runtime for self-hosted, non-Ubuntu, or non-x86_64 runners; use `docker-sbx` or `gvisor` instead. ## ARC DinD guidance diff --git a/.github/aw/memory.md b/.github/aw/memory.md index 871898f4889..0f34c646932 100644 --- a/.github/aw/memory.md +++ b/.github/aw/memory.md @@ -92,6 +92,20 @@ tools: retention-days: 14 ``` +### Custom validation + +For domain-specific constraints beyond `allowed-extensions` (schema checks, cross-file uniqueness, timestamp policies), add `validation.script` — a Node.js script body (globals: `fs`, `path`, `memoryRoot`, `memoryId`, `memoryKind`) run over the memory directory after agent execution and before persistence. Throwing, returning `false`, timing out, or exiting nonzero rejects the save. Default timeout 1 minute (`validation.timeout-minutes`, max 5). Same mechanism for `repo-memory`. See [cache-memory reference](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/cache-memory.md#custom-validation) and [repo-memory reference](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/repo-memory.md#custom-validation). + +```yaml +tools: + cache-memory: + validation: + timeout-minutes: 1 + script: | + const index = JSON.parse(fs.readFileSync(path.join(memoryRoot, "index.json"), "utf8")); + if (!Array.isArray(index.entries)) throw new Error("index.json entries must be an array"); +``` + ### Storage path - Single cache: `/tmp/gh-aw/cache-memory/` diff --git a/.github/aw/syntax-agentic.md b/.github/aw/syntax-agentic.md index 1d407e6e669..55a0662074b 100644 --- a/.github/aw/syntax-agentic.md +++ b/.github/aw/syntax-agentic.md @@ -154,6 +154,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - Preferred: provide GitHub App credentials (`app-id`/`client-id` + `private-key`) to mint a token with `actions/create-github-app-token` before `actions/setup`. - OIDC mode is used when `github-app` is configured without credentials (`app-id`/`client-id` + `private-key`). - OIDC mode requires `permissions.id-token: write` on the workflow/job. + - `workload-identity:` - Exchange a GitHub Actions OIDC token for a cloud access token before OTLP export. Only `provider: google` is currently supported; requires `audience:` (Google Workload Identity Provider resource name) and accepts optional `service-account:` to impersonate after STS token exchange. - `headers:` - Comma-separated `key=value` HTTP headers included in every OTLP export request (e.g. `Authorization=Bearer `). Injected as `OTEL_EXPORTER_OTLP_HEADERS`. Supports GitHub Actions expressions. - `resource-attributes:` - Optional map of additional OTEL resource attributes appended to gh-aw/GitHub defaults. Values may be static strings or GitHub Actions expressions. Do not use `secrets.*` or `vars.*` here because resource attributes are exported to external observability backends and are not treated as secret values. - Example: @@ -179,6 +180,7 @@ description: Agentic workflow specific frontmatter fields for GitHub Agentic Wor - `action-repo:` - GitHub Actions repository for setup (e.g., 'actions/setup-node') - `action-version:` - Version of the setup action (e.g., 'v4', 'v5') - `if:` - Optional GitHub Actions condition to control when runtime setup runs (e.g., `"hashFiles('go.mod') != ''"`) + - `cooldown:` - Enable a default 3-day dependency cooldown for installs on this runtime (boolean, default: `true`); set `false` to disable - Example: ```yaml diff --git a/.github/aw/syntax-engine.md b/.github/aw/syntax-engine.md index 600a7eab315..5ddfa38974d 100644 --- a/.github/aw/syntax-engine.md +++ b/.github/aw/syntax-engine.md @@ -86,4 +86,4 @@ See [syntax-agentic.md](syntax-agentic.md) for the full frontmatter field index. Constraints: exactly one runtime key per `driver` object; source must be non-empty; only supported on the `copilot` engine. Use `runtimes..version` to pin the runtime version used for the generated module files (e.g. `runtimes.go.version: "1.22"`). - **`engine.auth:`** — keyless Workload Identity Federation via the AWF API proxy instead of a static API key; requires `id-token: write`. Set `type: github-oidc` (only supported type) plus `provider: azure` (`azure-tenant-id`, `azure-client-id`, optional `azure-scope`/`azure-cloud`) for Azure OpenAI, `provider: anthropic` (`federation-rule-id`, `organization-id`, `service-account-id`, `workspace-id`) for Claude, or `provider: gcp` (`workload-identity-provider`, `service-account`, optional `project`/`location`, default region `us-central1`) for Vertex AI / Gemini Enterprise. Optional `audience:`. Maps to `AWF_AUTH_*` env vars. - - **Advanced engine sub-fields** (see the `engine_config` definition in `pkg/parser/schemas/main_workflow_schema.json`): `model-provider` (`github` | `anthropic` | `openai`), `harness` (retry policy), engine-level `mcp` (`session-timeout`/`tool-timeout`), `extensions`, and `cwd`. + - **Advanced engine sub-fields** (see the `engine_config` definition in `pkg/parser/schemas/main_workflow_schema.json`): `model-provider` (`github` | `anthropic` | `openai`), `harness` (`max-retries`/`initial-delay-ms`/`backoff-multiplier`/`max-delay-ms` retry policy, plus `watchdog-timeout` — a post-result idle-process watchdog, in seconds, for the built-in Copilot/Codex harnesses), engine-level `mcp` (`session-timeout`/`tool-timeout`), `extensions`, and `cwd`. See [Harness Settings and Runtime Tuning Variables](https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/environment-variables.md#harness-settings-and-runtime-tuning-variables) for defaults, units, and `GH_AW_HARNESS_*` env var equivalents.