Skip to content

Add comprehensive strict mode reference documentation #4224

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Nov 17, 2025
Merged

Add comprehensive strict mode reference documentation #4224

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
e5002df
Initial plan
Copilot Nov 17, 2025
700ae10
Add comprehensive strict mode reference documentation
Copilot Nov 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 11 additions & 2 deletions docs/src/content/docs/guides/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,9 +178,18 @@ network:

Or via CLI: `gh aw compile --strict`

**Enforces**: write permissions blocked (use `safe-outputs`), explicit network configuration required, no network wildcards, MCP network configuration required.
**Enforcement Areas:**

**Benefits**: Minimizes attack surface, ensures compliance, improves auditability. CLI flag takes precedence over frontmatter. See [Frontmatter Reference](/gh-aw/reference/frontmatter/#strict-mode-strict).
Strict mode enforces the following security constraints:

1. **Write Permissions**: Blocks `contents:write`, `issues:write`, and `pull-requests:write`. Use `safe-outputs` instead.
2. **Network Configuration**: Requires explicit network configuration (no implicit defaults).
3. **Network Wildcards**: Refuses wildcard `*` in `network.allowed` domains.
4. **MCP Network**: Requires network configuration for custom MCP servers with containers.
5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.

Comment on lines +189 to +191
Copy link

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation lists "Action Pinning" as enforcement area #5, but action pinning is not validated in the validateStrictMode() function in strict_mode_validation.go. Instead, strict mode affects action pinning behavior indirectly through GetActionPinWithData() in action_pins.go (lines 121-127), which returns an error when an action cannot be pinned.

This enforcement happens during the compilation/pinning process, not as part of the centralized strict mode validation checks. The documentation should clarify that action pinning enforcement occurs during compilation, not as a validation check, or consider removing it from the "Enforcement Areas" list to accurately reflect what validateStrictMode() actually validates.

Suggested change
5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
5. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
> [!NOTE]
> **Action Pinning:**
> Action pinning (requiring GitHub Actions to be pinned to specific commit SHAs) is always enforced during the compilation process, not as part of strict mode validation. Strict mode may affect action pinning behavior, but the enforcement occurs during compilation, not as a strict mode validation check.

Copilot uses AI. Check for mistakes.
**Benefits**: Minimizes attack surface, ensures compliance, improves auditability. CLI flag takes precedence over frontmatter and applies to all workflows. See [Frontmatter Reference](/gh-aw/reference/frontmatter/#strict-mode-strict) and [CLI Commands](/gh-aw/setup/cli/#compile) for complete documentation.

#### Limit workflow longevity by `stop-after:`

Expand Down
27 changes: 25 additions & 2 deletions docs/src/content/docs/reference/frontmatter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,9 +183,32 @@ Enables enhanced validation for production workflows, enforcing security constra
strict: true # Enable (default: false)
```

Strict mode enforces: (1) no write permissions for `contents`, `issues`, or `pull-requests` (use `safe-outputs` instead), (2) explicit network configuration required, (3) no wildcard `*` in `network.allowed`, (4) network configuration for custom MCP servers with containers.
**Enforcement Areas:**

Enable with `strict: true` in frontmatter or `gh aw compile --strict` (CLI flag applies to all workflows and takes precedence). Use for production workflows requiring enhanced security validation or security policy compliance.
Strict mode enforces the following security constraints:

1. **Write Permissions**: Refuses `contents:write`, `issues:write`, and `pull-requests:write` permissions. Use [safe-outputs](/gh-aw/reference/safe-outputs/) instead for GitHub API write operations.

2. **Network Configuration**: Requires explicit network configuration. No implicit defaults allowed. See [Network Permissions](/gh-aw/reference/network/).

3. **Network Wildcards**: Refuses wildcard `*` in `network.allowed` domains. Specify explicit domains or use ecosystem identifiers.

4. **MCP Network**: Requires network configuration for custom MCP servers with containers.

5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs instead of tags or branches.

6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.

Comment on lines +198 to +201
Copy link

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation lists "Action Pinning" as enforcement area #5, but action pinning is not validated in the validateStrictMode() function in strict_mode_validation.go. Instead, strict mode affects action pinning behavior indirectly through GetActionPinWithData() in action_pins.go (lines 121-127), which returns an error when an action cannot be pinned.

This enforcement happens during the compilation/pinning process, not as part of the centralized strict mode validation checks. The documentation should clarify that action pinning enforcement occurs during compilation, not as a validation check, or consider removing it from the "Enforcement Areas" list to accurately reflect what validateStrictMode() actually validates.

Suggested change
5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs instead of tags or branches.
6. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
5. **Deprecated Fields**: Refuses use of deprecated frontmatter fields.
> **Note:** Strict mode also enforces that all GitHub Actions must be pinned to specific commit SHAs (not tags or branches). This enforcement occurs during the compilation process, not as part of the strict mode validation checks.

Copilot uses AI. Check for mistakes.
**Enabling Strict Mode:**

Strict mode can be enabled in two ways:

- **Frontmatter field**: `strict: true` (per-workflow control)
- **CLI flag**: `gh aw compile --strict` (applies to all workflows, takes precedence)

The CLI flag enables strict mode for all workflows being compiled and cannot be overridden by individual workflow frontmatter. The frontmatter field allows per-workflow strict mode but cannot disable strict mode when the CLI flag is set.

See [CLI Commands](/gh-aw/setup/cli/#compile) for detailed `--strict` flag documentation and [Security Guide](/gh-aw/guides/security/#strict-mode-validation) for security best practices.

### Feature Flags (`features:`)

Expand Down
36 changes: 35 additions & 1 deletion docs/src/content/docs/setup/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,13 +141,47 @@ Remote imports are automatically cached in `.github/aw/imports/` for offline com
| Option | Description |
|--------|-------------|
| `--validate` | Schema validation and container checks |
| `--strict` | Requires timeouts, explicit network config, blocks write permissions |
| `--strict` | Enable strict mode validation for all workflows |
| `--zizmor` | Security scanning with [zizmor](https://github.com/woodruffw/zizmor) |
| `--dependabot` | Generate npm/pip/Go manifests and update dependabot.yml |
| `--json` | Output validation results in machine-readable JSON format |
| `--watch` | Auto-recompile on file changes |
| `--purge` | Remove orphaned `.lock.yml` files |

**Strict Mode (`--strict`):**

The `--strict` flag enables enhanced security validation for all workflows during compilation. This flag is recommended for production workflows that require strict security compliance.

When enabled, strict mode enforces:

1. **No Write Permissions**: Blocks `contents:write`, `issues:write`, and `pull-requests:write` permissions. Use [safe-outputs](/gh-aw/reference/safe-outputs/) instead.

2. **Explicit Network Configuration**: Requires explicit `network` configuration. No implicit defaults allowed.

3. **No Network Wildcards**: Refuses wildcard `*` in `network.allowed` domains. Use explicit domains or ecosystem identifiers.

4. **MCP Server Network**: Requires network configuration for custom MCP servers with containers.

5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.

6. **No Deprecated Fields**: Refuses deprecated frontmatter fields.
Comment on lines +165 to +167
Copy link

Copilot AI Nov 17, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The documentation lists "Action Pinning" as enforcement area #5, but action pinning is not validated in the validateStrictMode() function in strict_mode_validation.go. Instead, strict mode affects action pinning behavior indirectly through GetActionPinWithData() in action_pins.go (lines 121-127), which returns an error when an action cannot be pinned.

This enforcement happens during the compilation/pinning process, not as part of the centralized strict mode validation checks. The documentation should clarify that action pinning enforcement occurs during compilation, not as a validation check, or consider removing it from the "Enforcement Areas" list to accurately reflect what validateStrictMode() actually validates.

Suggested change
5. **Action Pinning**: Enforces GitHub Actions to be pinned to specific commit SHAs.
6. **No Deprecated Fields**: Refuses deprecated frontmatter fields.
5. **No Deprecated Fields**: Refuses deprecated frontmatter fields.
**Note:** Action pinning (requiring all GitHub Actions to be pinned to specific commit SHAs) is always enforced during the compilation process. In strict mode, any unpinned actions will cause compilation to fail, but this is enforced during compilation/pinning, not as part of strict mode validation checks.

Copilot uses AI. Check for mistakes.

**Precedence:** The `--strict` CLI flag applies to all workflows being compiled and takes precedence over individual workflow `strict` frontmatter fields. Workflows cannot opt-out of strict mode when the CLI flag is set.

**Example:**
```bash wrap
# Enable strict mode for all workflows
gh aw compile --strict

# Strict mode with security scanning (fails on findings)
gh aw compile --strict --zizmor

# Validate schema and enforce strict mode
gh aw compile --validate --strict
```

See [Strict Mode reference](/gh-aw/reference/frontmatter/#strict-mode-strict) for frontmatter configuration and [Security Guide](/gh-aw/guides/security/#strict-mode-validation) for best practices.

### Testing

#### `trial`
Expand Down
Loading