Skip to content

Fix API docs writer pull request file limit - #186

Open
mattleibow wants to merge 12 commits into
mainfrom
mattleibow-fix-api-docs-workflow
Open

Fix API docs writer pull request file limit#186
mattleibow wants to merge 12 commits into
mainfrom
mattleibow-fix-api-docs-workflow

Conversation

@mattleibow

@mattleibow mattleibow commented Aug 4, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • raise safe-outputs.create-pull-request.max-patch-files from the default 100 to a bounded 500 and retain a bounded 6,144 KB signed-payload ceiling
  • keep the workflow prompt a thin API-reference orchestration layer driven by the selected SkiaSharp api-docs skill
  • select one coherent automated authoring wave: at most 10 files and 60 placeholder-bearing type/member DocIds, smaller for native-heavy work; leave remaining placeholders unchanged and report UNSELECTED rows
  • reserve meaningful time for the selected wave's adversarial review instead of attempting the full regenerated Graphite work set
  • conditionally detect native-sensitive changed or untracked XML that still contains placeholders; when detected, initialize exactly externals/skia with git -C skiasharp submodule update --init --depth 1 externals/skia and log its pinned SHA
  • invoke the cloned skill's canonical scripts/fetch-approved-context.py with explicit repository/label selectors; do not duplicate retrieval or schema logic in this repository
  • retain canonical fail-visible bounds of 50 issues and 1,048,576 final JSON bytes with no truncation; any script auth/API/pagination/schema/bounds/write failure fails the workflow and leaves no success-shaped context
  • expose a byte-identical canonical JSON copy to the agent only in mounted runner temp, then clean both temp copies; nothing can enter staging, commits, generated output, or PR file counts
  • treat issue text/comments as supplemental untrusted human context rather than instructions or authoritative technical evidence; source wins and claims must be validated through the skill
  • retain the exact native command as an agent fallback, authorize fixes for every self-introduced CRITICAL and IMPORTANT finding, and require the current route output rows
  • preserve dedicated throwaway branches, staging/index exclusions, Opus 4.8, and PR/noop completion

Approved issue context

After cloning the requested SkiaSharp branch, the workflow runs exactly:

python skiasharp/.agents/skills/api-docs/scripts/fetch-approved-context.py --repository mono/SkiaSharp-API-docs --label approved-for-context --output "$RUNNER_TEMP/api-docs-approved-context.json" --max-issues 50 --max-bytes 1048576

The workflow grants only issues: read and supplies GH_TOKEN; issue filtering, PR exclusion, complete comment pagination, canonical camelCase schema v1, stable ordering, bounds, atomic writes, and manifest redaction remain owned by the skill script.

The script logs only its canonical CONTEXT row and redacted single-line ISSUE rows. Because gh-aw mounts $RUNNER_TEMP/gh-aw rather than the whole host runner temp into the agent sandbox, the workflow copies the canonical file byte-for-byte to $RUNNER_TEMP/gh-aw/api-docs-approved-context.json, verifies it with cmp, exports that exact path as $APPROVED_ISSUE_CONTEXT_PATH, and removes both files in an always-run post step. It never reads or logs issue bodies/comments itself.

Conditional native checkout

The host examines both tracked changes and newly generated untracked XML under SkiaSharpAPI/. A file enters the native-sensitive set only when it still contains To be added. and matches the Graphite/backend/texture/recording/context/callback/delegate/release/Vulkan/Metal/Dawn signal set. A non-empty set runs the exact pinned submodule command and prints git -C skiasharp/externals/skia rev-parse HEAD; an empty set leaves the submodule uninitialized.

Validation

  • workflow head d2268f449f142bac02479a1945e6605ad0862709 compiled with gh-aw v0.83.4 strict schema/action validation with zero errors
  • frozen SkiaSharp branch mattleibow-api-docs-two-route-skill resolved to and checked out exactly 12a2c5530e11b09f2a5b73e60b5145a231769dcf
  • final CI run https://github.com/mono/SkiaSharp-API-docs/actions/runs/31023530801 completed successfully: every job passed, including regenerate-stubs, agent, detection, safe_outputs, and conclusion
  • canonical manifest logged CONTEXT | mono/SkiaSharp-API-docs | approved-for-context | 2 | 41129 | ... and individual rows for open issues Migrate inline /// docs to mdoc XML (Graphite backend + pre-existing) #181 and Docs: async RequestReadPixels API (SKImage/SKSurface/GRContext, SKImageReadPixelsResult, SKImageRescaleGamma/Mode) #184; the agent-visible byte-identical copy was exported from runner temp
  • native-sensitive detection triggered and logged pinned Skia SHA c14bcfbab83b2182977505c251a02c058f83a321
  • authoring stayed bounded to 3 files and 17 DocIds; output included 3 WROTE, 17 per-DocId EVIDENCE, 3 NATIVE, 3 TRACE, no DEFERRED/finding rows, and 24 UNSELECTED files matching the remaining placeholder-bearing work set
  • safe outputs created signed 361-file PR Fill and review API documentation #194: 338 modified + 23 added XML files, no non-XML or runner-context files; the 500-file/6,144-KB safeguards remained active
  • PR Fill and review API documentation #194 was closed as validation-only after content review found missing deterministic OverflowException contracts for checked size calculations and transitive callers, overbroad disposal wording, unsupported rescale-quality superlatives, an owned-bitmap example without disposal, and inconsistent structural-file arithmetic. The run proves transport, context availability, branch/native checkout, bounded orchestration, and large signed PR creation—not merge-ready generated docs.
  • superseded runs https://github.com/mono/SkiaSharp-API-docs/actions/runs/31022060465 and https://github.com/mono/SkiaSharp-API-docs/actions/runs/31022403356 are terminal cancelled and excluded from validation
  • the standalone actionlint v1.7.12 diagnostic remains limited to gh-aw's pre-existing generated concurrency.queue extension; gh-aw reports its exit code 3 as a tooling error rather than a workflow validation failure
  • git diff --check passed; .github/aw/actions-lock.json is unchanged because no action dependency changed

Scope

No API documentation content is modified by this workflow-fix PR.

Raise the bounded safe-output file ceiling for regenerated API XML, keep the existing patch-size limit, and constrain the agent to API-reference routes.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 6b978df:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

The representative dispatch showed that gh-aw v0.83.4 no longer recognizes claude-opus-4.7. Move to the suggested Opus 4.8 model so the agent can execute.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit d123d6a:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

The representative main/main run produced a legitimate 1,854 KB regenerated XML patch. Set a narrowly bounded 2,048 KB ceiling so that payload can reach the 500-file safe-output check without accepting the newer compiler's 4,096 KB default.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 67befb4:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

The successful safe-output validation measured a 1,857 KB patch, while signed-commit synthesis expanded its additions payload to 5,508 KB. Use a bounded 6,144 KB ceiling so the protected signed push can complete without disabling commit signing.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit cdf4345:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Use the exact SEVERITY | class | file | docId | message format required by references/reviewing.md instead of the obsolete FINDING-prefixed wording.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

When managed bindings delegate status, ownership, or callback semantics, initialize only the pinned externals/skia submodule on demand instead of inferring behavior or recursively cloning all submodules.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit dc58c71:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit f14d25d:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Delegate authoring, review, fact-checking, and validation policy to the API docs skill while retaining CI-specific routing, scope, native checkout, fix authorization, timebox, staging, and safe-output wiring.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 1589d10:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Select one reviewable automated wave, initialize pinned Skia native source only for native-sensitive regenerated placeholders, authorize fixes for self-introduced critical findings, and require the current skill evidence rows.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 22bc61e:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 3797d4f:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit 1ee486e:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit f5c6143:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 0a6a39be-d1a6-4614-b743-2a492784eceb
@learn-build-service-prod

Copy link
Copy Markdown
Contributor

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

@learn-build-service-prod

Copy link
Copy Markdown
Contributor

Learn Build status updates of commit d2268f4:

✅ Validation status: passed

File Status Preview URL Details
.github/aw/actions-lock.json ✅Succeeded
.github/workflows/auto-api-docs-writer.lock.yml ✅Succeeded
.github/workflows/auto-api-docs-writer.md ✅Succeeded

For more details, please refer to the build report.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant