docs(gh-aw): replace deprecated dependencies: with shared/apm.md import#864
Merged
danielmeppiel merged 6 commits intomainfrom Apr 23, 2026
Merged
docs(gh-aw): replace deprecated dependencies: with shared/apm.md import#864danielmeppiel merged 6 commits intomainfrom
danielmeppiel merged 6 commits intomainfrom
Conversation
gh-aw deprecated the top-level 'dependencies:' frontmatter field in favor of the 'imports: - uses: shared/apm.md with: packages:' pattern. Our integration page still presented 'dependencies:' as 'Recommended' and included an 'Isolated Mode' section tied to the deprecated object form. Changes: - Renamed primary section to 'Shared apm.md Import (Recommended)' with the canonical pattern from gh-aw reference docs (matches how this repo's own .github/workflows/pr-review-panel.md consumes APM). - Added a package reference format table that explicitly documents the three forms: full package, individual primitive (any layout), pinned ref. The per-primitive form is what lets workflows consume skills from repos like github/awesome-copilot that don't use the .apm/ layout, without restructuring them. - Added a deprecation callout pointing migrators away from the old 'dependencies:' field. - Removed the 'Isolated Mode' section -- it documented an option only reachable through the deprecated object form. - Updated the Bundles example to drop the inline imports list (which did not match the shared/apm.md pattern) and added a pointer to enterprise/registry-proxy as the live-routing complement to bundles. - Updated the Content Scanning paragraph to reference shared/apm.md resolution instead of the old dependencies-via-apm-action wording. Build: 42 pages, all internal links valid. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the gh-aw integration documentation to reflect gh-aw deprecating the top-level dependencies: frontmatter field, aligning this repo's guidance with the recommended imports: - uses: shared/apm.md pattern.
Changes:
- Replaces the deprecated
dependencies:workflow frontmatter example withimports: - uses: shared/apm.md+with: packages:. - Adds a small reference table describing supported package reference formats (full package, per-primitive path, pinned ref).
- Updates bundles and content-scanning sections to match the new shared import approach and adds a link to the enterprise registry proxy doc.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/integrations/gh-aw.md | Updates gh-aw integration guidance to the shared/apm.md import pattern, adds reference format table + deprecation callout, and refreshes related sections/links. |
Copilot's findings
- Files reviewed: 1/1 changed files
- Comments generated: 2
Adds a new conceptual page in Introduction that answers the recurring question: 'what is .apm/ and why does it exist?' Covers: - The src/dist mental model (.apm/ = src, .github/.claude/.cursor/ = dist, apm_modules/ = node_modules, apm.yml = package.json) - Why .apm/ exists: separates source primitives from per-runtime compiled output; avoids self-referential context pollution where the dev-time agent reads in-progress sources from .github/ - Why not .github/ directly (3 reasons), why not the repo root (3 reasons) - Two ways to be importable: package form (apm.yml + .apm/) vs primitive form (owner/repo/path/to/primitive virtual package) - Decision guide for consumers vs publishers - Dogfooding example: this very repo has .apm/skills/ as source and byte-identical .github/skills/ as compiled output the in-repo Copilot agent reads - Discovery rules and quick FAQ (ls -a tip, overwrite-on-install warning) Wires: - Sidebar entry under 'Understanding APM' after Key Concepts - Link from integrations/gh-aw.md primitive-form table to this page Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Per doc-writer corpus-fit audit: Anatomy page additions: - New 'Why not just ship a plugin.json?' section after 'Why not the repo root?' that frames plugins as runtime distribution format vs .apm/ as source layout (complementary, not competing). Calls out the three concrete touchpoints: APM consumes plugins natively, exports to plugin format via 'apm pack --format plugin', and supports hybrid mode (apm.yml + plugin.json together). - FAQ entry mirroring the same point for skim readers. - Compressed dogfooding section to a back-link (was duplicating the earlier 'concrete example' block). Corpus DRY trims (anatomy is now the single source of truth for layout): - key-concepts.md: removed 'Supported Locations' tree (~30 lines that framed .apm/ and .github/ as equivalent source locations, contradicting anatomy). Replaced 'Organized Structure' tree and 'Integration with VSCode' section with one-line links to anatomy. - first-package.md: added one-line link to anatomy in the post-init note so step-2's '.apm/instructions/' is no longer introduced silently. - how-it-works.md: linked '.apm/ directory' bullet in the architecture caption to anatomy. - guides/plugins.md: added a leading link from 'Plugin authoring' to the new plugin-skeptic section in anatomy (round-trip). Net word count across corpus: down (~60 lines trimmed vs ~40 added). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Agent-Logs-Url: https://github.com/microsoft/apm/sessions/31d38cde-05ac-45e5-8d5b-fdd4186014f8 Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
danielmeppiel
added a commit
that referenced
this pull request
Apr 23, 2026
…t webhooks (#865) * ci: add merge-gate orchestrator (shadow) + stuck-PR watchdog PR #856 surfaced a structural CI fragility: required status checks are satisfied by two independent webhook channels (pull_request emits 'Build & Test (Linux)', pull_request_target emits the four Tier 2 stubs). When the pull_request delivery is dropped, 4/5 stubs go green and the 5th hangs in 'Expected -- Waiting' forever -- ambiguous yellow indistinguishable from a slow build. Recovery is folklore. This PR ships two safety nets in shadow mode: * .github/workflows/merge-gate.yml + scripts/ci/merge_gate_wait.sh Single orchestrator that polls the Checks API for 'Build & Test (Linux)' on the PR head SHA and aggregates into one verdict. Triggers on BOTH pull_request and pull_request_target so a single dropped delivery is recoverable; concurrency dedupes. Times out cleanly with a clear error message if Tier 1 never dispatched -- turning the invisible failure into a loud red check. NOT YET REQUIRED -- shadow observation first, ruleset flip after merge. * .github/workflows/watchdog-stuck-prs.yml + scripts/ci/watchdog_scan.sh Cron every 15 min. For open non-draft PRs with no ci.yml run on the head SHA AND non-paths-ignored files, posts one recovery comment. Backstop for any required check that stops dispatching. Tested live (dry-run) against microsoft/apm: watchdog correctly distinguishes stuck PRs (#853, #409) from docs-only PRs (#864, #461, #825). Both scripts shellcheck-clean. merge_gate_wait.sh tested end-to-end against PR #856 head SHA (success path, exit 0) and a non-existent SHA (timeout path, exit 2 with clear error annotation). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci(merge-gate): handle self-bootstrap and use checkout on pull_request Two fixes for the script-fetch step: 1. On 'pull_request' the runner has no secrets and a read-only token, so actions/checkout of PR head is safe -- use it for simplicity. We only need API-fetch under 'pull_request_target' where checkout would be a security risk. 2. On 'pull_request_target', when the script does not yet exist on base (i.e. THIS PR is the one adding it), curl returns 404 and we degrade to a self-bootstrap no-op pass instead of failing. Once the script lands on main, the gate becomes real. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: address Copilot review feedback on PR #865 - merge_gate_wait.sh: use $EXPECTED_CHECK in failure annotation instead of hardcoded 'Build & Test (Linux)' so the orchestrator stays generic. - merge-gate.yml: add curl --retry/--max-time on the script bootstrap fetch so a transient GitHub API blip does not redden the gate. - watchdog_scan.sh: fail loudly with stderr capture if 'gh pr list' errors out, instead of silently treating it as zero PRs (which would hide auth regressions or rate limiting). - watchdog_scan.sh: paginate the changed-files API call so PRs touching >100 files cannot be misclassified as docs-only and skipped. - CHANGELOG: append (#865) to follow the repo convention. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: drop watchdog -- gate's dual-trigger redundancy is sufficient The watchdog (cron every 15min, posts recovery comments on stuck PRs) was originally justified for the shadow-mode transition window. Since we are flipping to required immediately after this PR merges, that justification disappears. The merge-gate workflow already triggers on both 'pull_request' and 'pull_request_target' with concurrency dedup, so a single dropped webhook still fires the gate. The watchdog only added value for the double-drop case (both webhook channels fail for the same PR), which is vanishingly rare. We can add it back later if we ever observe one. Removes: - .github/workflows/watchdog-stuck-prs.yml - .github/scripts/ci/watchdog_scan.sh Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This was referenced Apr 23, 2026
danielmeppiel
added a commit
that referenced
this pull request
Apr 23, 2026
* chore: prepare v0.9.2 release Bumps version to 0.9.2 and finalizes CHANGELOG with one-line summaries for each PR merged since 0.9.1. Highlights: - ADO AAD bearer-token auth (#856) - Governance Guide + enterprise docs IA refactor (#851, #858) - Merge Gate orchestrator + single-authority aggregation (#865, #867) - Landing + first-package docs rewrite (#855, #866) - gh-aw imports migration (#864) - Custom-port surfacing fix (#804) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: simplify merge-gate to single pull_request trigger The dual-trigger pattern (pull_request + pull_request_target with concurrency cancel-in-progress) shipped in #865 was over-engineered. It produced TWO 'gate' check-runs per SHA -- one SUCCESS, one CANCELLED -- and branch protection's status-check rollup treats CANCELLED as failure, so PRs were silently BLOCKED unless an admin overrode (which masked the bug on #867). GitHub Actions has no primitive for 'either of these events succeeded'. World-class OSS projects (kubernetes, rust, deno, next.js) accept this and use a single trigger. The cost: a dropped 'pull_request' webhook (rare; observed once on PR #856) requires manual recovery. Recovery paths now documented at top of file: - push empty commit - gh workflow run merge-gate.yml -f pr_number=NNN - close + reopen PR Replaces the dual-trigger + bootstrap-fetch dance with a clean two-job flow: resolve-sha (handles workflow_dispatch input or PR head) then gate (sparse checkout + run script). Same script, same exit codes, same EXPECTED_CHECKS env. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: collapse merge-gate into a single job (one check-run in PR UI) The two-job split (resolve-sha + gate) created two visible check-runs. Inlining the SHA resolution as a step within the gate job leaves only one check-run -- 'Merge Gate / gate' -- on the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
gh-aw deprecated the top-level
dependencies:frontmatter field. Ourintegrations/gh-aw.mdpage still presented it as the recommended pattern. This PR replaces it with the canonicalimports: - uses: shared/apm.md with: packages:form (per the gh-aw reference and how this repo's own.github/workflows/pr-review-panel.mdalready consumes APM).Why this matters
A user (#community) just hit this: existing repo with skills laid out at
/skills/<name>/(not under.apm/), wanted to import them into a gh-aw workflow. Our doc told them to use a syntax gh-aw rejects, and didn't make clear that the per-primitive reference form (owner/repo/path/to/skill) lets them consume those skills with no restructure.Changes
github/awesome-copilot/skills/review-and-refactorworks because the per-primitive form does not require the source repo to use.apm/.dependencies:.imports:list (which didn't matchshared/apm.mdeither) and adds a pointer to the newenterprise/registry-proxypage as the live-routing complement to bundles.shared/apm.mdresolution.Verification
cd docs && npm run build-> 42 pages, all internal links valid.