Skip to content

[docs] Self-healing documentation fixes from issue analysis - 2026-06-20 #40402

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 1 commit into from
Jun 20, 2026
Merged

[docs] Self-healing documentation fixes from issue analysis - 2026-06-20 #40402

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 14 additions & 0 deletions docs/src/content/docs/reference/engines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -419,6 +419,20 @@ engine:

Custom weights are embedded in the compiled workflow YAML and read by `gh aw logs` and `gh aw audit` when analyzing runs.

### Pi Extensions (`extensions`)

The Pi engine supports loading additional plugins via `engine.extensions`. Each entry is an npm package name installed with `pi install <extension>` before the agent runs. Only the Pi engine reads this field; other engines ignore it.

```yaml wrap
engine:
id: pi
extensions:
- "@pi/web-search"
- "@pi/file-browser"
```

Each listed extension produces one additional install step in the compiled workflow. If `engine.command` is set, the same executable is used to install the extensions.

@github-actions github-actions Bot Jun 20, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Factual error: the claim that engine.command delegates extension installation to the same executable is incorrect — extensions are silently skipped when engine.command is set.

💡 What the code actually does

GetInstallationSteps in pkg/workflow/pi_engine.go has an early-return guard:

if workflowData.EngineConfig != nil && workflowData.EngineConfig.Command != "" {
    // Skipping installation steps: custom command specified
    return []GitHubActionStep{}
}

This causes the function to return an empty step list before it ever reaches the extension-install loop. The commandName = workflowData.EngineConfig.Command assignment inside that loop is dead code.

A user who sets both engine.command and engine.extensions will find their extensions are never installed — no error is emitted, just silence.

Suggested correction:

Each listed extension produces one additional install step in the compiled workflow.
Note: engine.extensions has no effect when engine.command is set — the Pi CLI install step and all extension install steps are skipped in that configuration.

@github-actions github-actions Bot Jun 20, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

[/grill-with-docs] The claim about engine.command is contradicted by the source code — extensions are not installed when engine.command is set.

💡 Details

pi_engine.go:GetInstallationSteps has an early return when engine.command is set:

if workflowData.EngineConfig != nil && workflowData.EngineConfig.Command != "" {
    return []GitHubActionStep{} // skips ALL install steps
}

The commandName = workflowData.EngineConfig.Command branch inside the extensions loop (line 206) is therefore dead code — it can never be reached.

The last sentence should instead read something like:

Extensions are only installed when the default Pi CLI installer runs. If engine.command is set, all installation steps (including extensions) are skipped.

This matters for users who supply a custom engine.command and expect extensions to be auto-installed.


## Timeout Configuration

Repositories with long build or test cycles require careful timeout tuning at multiple levels. This section documents the timeout knobs available for each engine.
Expand Down
Loading