From f69373dda0c9e3971bf8486277d88b417b1fac72 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 28 May 2026 00:10:34 +0000 Subject: [PATCH] [docs] Fix broken anchors for check-for-updates and run-install-scripts Closes #34686. Adds the two missing frontmatter reference sections that the JSON Schema's `See:` links pointed to, and updates the schema URLs to match the actual anchor slugs Astro Starlight generates from the new headings. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../docs/reference/frontmatter-full.md | 4 +-- .../src/content/docs/reference/frontmatter.md | 32 +++++++++++++++++++ pkg/parser/schemas/main_workflow_schema.json | 4 +-- 3 files changed, 36 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/reference/frontmatter-full.md b/docs/src/content/docs/reference/frontmatter-full.md index fe1c42eec28..a26de9814f6 100644 --- a/docs/src/content/docs/reference/frontmatter-full.md +++ b/docs/src/content/docs/reference/frontmatter-full.md @@ -7690,7 +7690,7 @@ private: true # gh-aw repository and verifies the compiled version is not blocked and meets the # minimum supported version. Set to false to disable the check (not allowed in # strict mode). See: -# https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates +# https://github.github.com/gh-aw/reference/frontmatter/#update-check-check-for-updates # (optional) check-for-updates: true @@ -7701,7 +7701,7 @@ check-for-updates: true # supply chain security warning is emitted at compile time; in strict mode this is # an error. Per-runtime control is also available via # runtimes..run-install-scripts. See: -# https://github.github.com/gh-aw/reference/frontmatter/#run-install-scripts +# https://github.github.com/gh-aw/reference/frontmatter/#install-scripts-run-install-scripts # (optional) run-install-scripts: true diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md index 1a819eb7268..a4ccfd6cc58 100644 --- a/docs/src/content/docs/reference/frontmatter.md +++ b/docs/src/content/docs/reference/frontmatter.md @@ -508,6 +508,38 @@ The `private:` field only blocks installation via `gh aw add`. It does not affec Enable experimental or optional compiler and runtime behaviors as key-value pairs. See [Feature Flags](/gh-aw/reference/feature-flags/) for complete documentation. +### Update Check (`check-for-updates:`) + +Controls whether the activation job verifies the workflow was compiled with a supported version of gh-aw. + +```yaml wrap +check-for-updates: true # default +``` + +When `check-for-updates: true` (the default), the activation job downloads `config.json` from the gh-aw repository and verifies the compiled version is not blocked and meets the minimum supported version. Set `check-for-updates: false` to skip this step — for example in air-gapped environments — but the workflow will no longer detect that it was compiled with an outdated or blocked version of gh-aw. + +`check-for-updates: false` is not allowed in [strict mode](#strict-mode-strict). In non-strict mode it emits a compile-time warning. + +### Install Scripts (`run-install-scripts:`) + +Allows npm `pre`/`post` install scripts to execute during package installation. + +```yaml wrap +run-install-scripts: true +``` + +By default, the compiler appends `--ignore-scripts` to every generated npm install command to block install-time hooks, which are a common supply-chain attack vector. Setting `run-install-scripts: true` disables this protection globally for every runtime that generates npm install commands (currently `node`). The compiler emits a supply-chain security warning; in [strict mode](#strict-mode-strict) this is a compilation error. + +For finer-grained control, set the flag per runtime under [`runtimes:`](#runtimes-runtimes) instead: + +```yaml wrap +runtimes: + node: + run-install-scripts: true +``` + +Only enable this flag when you trust every installed package and its transitive dependencies. + ### Strict Mode (`strict:`) Disables enhanced security validation for production workflows. diff --git a/pkg/parser/schemas/main_workflow_schema.json b/pkg/parser/schemas/main_workflow_schema.json index 6924a753cdd..e6c03b96511 100644 --- a/pkg/parser/schemas/main_workflow_schema.json +++ b/pkg/parser/schemas/main_workflow_schema.json @@ -9840,13 +9840,13 @@ "check-for-updates": { "type": "boolean", "default": true, - "description": "Control whether the compile-agentic version update check runs in the activation job. When true (default), the activation job downloads config.json from the gh-aw repository and verifies the compiled version is not blocked and meets the minimum supported version. Set to false to disable the check (not allowed in strict mode). See: https://github.github.com/gh-aw/reference/frontmatter/#check-for-updates", + "description": "Control whether the compile-agentic version update check runs in the activation job. When true (default), the activation job downloads config.json from the gh-aw repository and verifies the compiled version is not blocked and meets the minimum supported version. Set to false to disable the check (not allowed in strict mode). See: https://github.github.com/gh-aw/reference/frontmatter/#update-check-check-for-updates", "examples": [true, false] }, "run-install-scripts": { "type": "boolean", "default": false, - "description": "Allow npm pre/post install scripts to execute during package installation. By default, --ignore-scripts is added to all generated npm install commands to prevent supply chain attacks via malicious install hooks. Setting run-install-scripts: true disables this protection globally (all runtimes). A supply chain security warning is emitted at compile time; in strict mode this is an error. Per-runtime control is also available via runtimes..run-install-scripts. See: https://github.github.com/gh-aw/reference/frontmatter/#run-install-scripts", + "description": "Allow npm pre/post install scripts to execute during package installation. By default, --ignore-scripts is added to all generated npm install commands to prevent supply chain attacks via malicious install hooks. Setting run-install-scripts: true disables this protection globally (all runtimes). A supply chain security warning is emitted at compile time; in strict mode this is an error. Per-runtime control is also available via runtimes..run-install-scripts. See: https://github.github.com/gh-aw/reference/frontmatter/#install-scripts-run-install-scripts", "examples": [false, true] }, "mcp-scripts": {