[aw-compat] Common syntax errors: missing permissions, workflow_run branches, and doc files in workflows/

[github-actions]

Recurring user-facing syntax and configuration errors found in the 2026-04-17 daily compat check (§24548289602).

Error 1: Missing required permissions for toolsets

Repo: dotnet/aspnetcore (37,841 stars)
File: .github/workflows/issue-triage-agent.md

The workflow uses tools.github with min-integrity: none (which enables the pull_requests toolset) but only declares:

permissions:
  contents: read
  issues: read
```
Missing: `pull-requests: read`.

**Error**:
```
error: Missing required permissions for GitHub toolsets:
  - pull-requests: read (required by pull_requests)

Suggested fix:

permissions:
  contents: read
  issues: read
  pull-requests: read   # ← add this
```

**Codemod opportunity**: `gh aw fix` could auto-detect toolsets in use, derive required permissions, and add missing declarations to frontmatter.

---

### Error 2: `workflow_run` trigger without `branches:` restriction

**Repo**: [vercel/vercel](https://github.com/vercel/vercel) (15,311 stars)
**File**: `.github/workflows/ci-doctor.md`

```
error: workflow_run trigger should include branch restrictions for security and performance.
Without branch restrictions, the workflow will run for workflow runs on ALL branches.

The workflow_run trigger is defined without a branches: field. In strict mode, this is an error.

Suggested fix:

on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]
    branches:        # ← add branches restriction
      - main
```

This is intentional strict-mode enforcement, but users upgrading from older workflow versions may not be aware. The error message is already clear; consider making `gh aw fix` prompt for a branch name or insert a `[main]` default.

---

### Error 3: Non-workflow documentation `.md` file in `.github/workflows/`

**Repo**: [dotnet/aspnetcore](https://github.com/dotnet/aspnetcore) (37,841 stars)
**File**: `.github/workflows/labeler.md`

`labeler.md` is a pure documentation file (32 lines, no YAML frontmatter) describing how the labeler workflow system is structured. It happens to live in `.github/workflows/` alongside actual workflow files.

```
no frontmatter found
✗ compilation failed

The compiler picks it up because it has a .md extension. Since it has no YAML frontmatter at all, there is no way to "fix" it — it's not a workflow.

Options for the compiler:

1. Skip .md files with no frontmatter (warn instead of error)
2. Require an explicit exclude list (e.g. .github/workflows/.awignore)
3. Only compile files that begin with a YAML --- fence

References: §24548289602
Related to #26811

Generated by Daily AW Cross-Repo Compile Check · ● 911.5K · ◷

• expires on Apr 24, 2026, 5:05 AM UTC

[pelikhan]

@copilot the issue is that the github MCP server default toolset contains the pull requests tools.

Add a special case for the "default" toolset, when it is implied or just default - no other: Downgrade the error to a warning that states some of the tools will not be available.

[github-actions]

This issue is being closed as outdated. A newer issue has been created: #26846

View newer issue

---

This action was performed automatically by the Daily AW Cross-Repo Compile Check workflow.

[github-actions]

This issue is being closed as outdated. A newer issue has been created: #26847

View newer issue

---

This action was performed automatically by the Daily AW Cross-Repo Compile Check workflow.