Add automated GitHub Changelog and API change monitoring workflow

[MariusStorhaug]

Context

The PSModule/GitHub PowerShell module wraps the GitHub REST and GraphQL APIs. Keeping the module current with API changes requires manually monitoring the GitHub Changelog and the GitHub REST API OpenAPI specification for new, changed, or deprecated endpoints. Today this is a manual process — a maintainer notices a changelog entry, decides whether it affects the module, and creates an issue by hand.

This manual approach is unreliable and slow. Changes can go unnoticed for weeks or months, leading to the module missing new features, silently wrapping deprecated endpoints, or breaking when endpoint signatures change. Examples of issues that were created manually after noticing changelog entries include #566 (API version change to 2026-03-10) and #579 (OIDC custom property inclusions).

Request

An automated workflow should periodically check for GitHub API changes that are relevant to the module and create well-structured issues for each change that requires action. The workflow should run as a GitHub Actions workflow on a weekly schedule (with manual trigger support) and use the Issue Manager agent to produce issues that follow the repository's issue-driven development format — complete with context, technical decisions, and implementation plan sections.

Desired capability

• A scheduled GitHub Actions workflow detects relevant changes from the GitHub Changelog and/or the OpenAPI spec
• For each relevant change, the Issue Manager agent creates a well-structured issue on this repository with the appropriate context, linking back to the changelog entry or API spec diff that triggered it
• Duplicate issues are not created for changes that already have open issues
• Irrelevant changes (GitHub.com UI-only changes, GitHub Enterprise Server-only features, GitHub Desktop features, etc.) are filtered out automatically
• The created issues are optionally assigned to the Copilot coding agent for implementation

Acceptance criteria

• A workflow file exists in .github/workflows/ that runs on schedule (weekly) and workflow_dispatch
• The workflow fetches recent entries from the GitHub Changelog RSS feed and/or diffs the OpenAPI spec
• Relevant API changes are identified by comparing against the module's current function coverage in src/functions/public/ and src/functions/private/
• Each detected change results in a seed issue created via the GitHub API, then assigned to the Issue Manager agent (via Copilot coding agent) to structure into the full three-section format
• No duplicate issues are created — existing open issues are checked before creating new ones
• The workflow logs which changes were found, which were filtered out, and which issues were created

---

Technical decisions

Workflow file location: .github/workflows/Monitor-GitHubChangelog.yml — follows the existing convention of a single descriptive workflow name (like Process-PSModule.yml).

Trigger configuration: Both schedule (weekly, e.g., cron: '0 6 * * 1' for Monday 06:00 UTC) and workflow_dispatch for manual runs. The workflow_dispatch trigger should accept an optional input for the number of days to look back (defaulting to 7).

Data sources — two-pronged approach:

1. Primary: GitHub REST API OpenAPI spec — The authoritative source for API surface changes. The workflow downloads the bundled spec from https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json (same URL used in the existing tools/utilities/GitHubAPI.ps1 utility) and compares it against a previously stored snapshot. This detects new endpoints, removed endpoints, changed parameters, and new API versions.

2. Supplementary: GitHub Changelog RSS feed — Provides human-readable context about what changed and why. The RSS feed is parsed for entries within the lookback window. Each entry is checked for relevance to the REST/GraphQL API (filtering out UI-only, GHES-only, and non-API changes). Relevant entries are linked in the created issues for context.

State persistence: Store the previous OpenAPI spec hash (SHA-256) and the last-checked RSS entry timestamp in a JSON state file committed to a dedicated changelog-state branch (similar to how GitHub Pages uses a gh-pages branch). This avoids relying on Actions cache (which expires) and keeps the state versioned.

Relevance filtering logic:

Signal	Action
Changelog entry mentions REST API, GraphQL API, or specific endpoint paths	Include
Entry title contains "API", "endpoint", "REST", "GraphQL", "webhook"	Include
OpenAPI spec diff shows new/removed/changed paths	Include
Entry is about GitHub.com UI only (no API impact)	Exclude
Entry is about GitHub Enterprise Server only (ghes-* spec)	Exclude
Entry is about GitHub Desktop, GitHub Mobile, or Codespaces IDE	Exclude
Entry is about GitHub Copilot product features (not API)	Exclude
API change affects endpoints the module already covers (matched by tag or path)	Flag as high priority
API change affects endpoints not currently covered	Flag as new coverage opportunity

Module coverage mapping: The workflow should build a map of the module's current API coverage by:

• Scanning src/functions/private/ for Invoke-GitHubAPI calls and extracting the APIEndpoint values
• Mapping these to OpenAPI spec paths and tags
• Comparing against the OpenAPI spec to identify covered vs. uncovered endpoints

Duplicate detection: Before creating an issue, search existing open issues using the GitHub search API for:

• The changelog entry URL (if present in any open issue body)
• The affected endpoint path (e.g., /repos/{owner}/{repo}/actions/oidc)
• Keywords from the changelog entry title

Issue creation approach — Issue Manager agent: The workflow creates a seed issue for each relevant change via the GitHub Issues API. The seed issue contains structured context (changelog entry link, affected endpoints, current module coverage, suggested scope) — enough for the Issue Manager agent to pick up and format into the full three-section issue format. After creation, the issue is assigned to the Copilot coding agent which invokes the Issue Manager agent to structure it.

Labels for created issues:

Change type	Labels
New API endpoint not currently covered	feature
Change to an existing covered endpoint	patch
Breaking change to a covered endpoint	major
Deprecated endpoint currently covered	patch

Implementation language: PowerShell — consistent with the rest of the repository. The workflow runs on ubuntu-latest and uses pwsh shell. The core logic lives in utility scripts under tools/utilities/ (following the existing pattern of GitHubAPI.ps1).

Permissions required: The workflow needs contents: read (to read the repository and state branch), contents: write (to update the state branch), and issues: write (to create issues and search existing ones).

Breaking changes: None. This is a new workflow that does not affect existing functionality.

Test approach: The utility scripts should be testable independently by providing mock OpenAPI spec data and mock RSS feed content. A test script can verify the filtering logic, duplicate detection, and issue body formatting without actually calling the GitHub API.

---

Implementation plan

Workflow file

• Create .github/workflows/Monitor-GitHubChangelog.yml with schedule (weekly) and workflow_dispatch triggers
• Add workflow inputs: lookback-days (default: 7), assign-to-copilot (default: false), dry-run (default: false)
• Configure permissions: contents: write, issues: write
• Add concurrency group to prevent overlapping runs

Core utility scripts

• Create tools/utilities/Monitor-GitHubChangelog.ps1 as the main orchestrator script
• Create tools/utilities/Get-GitHubChangelogEntries.ps1 to fetch and parse the RSS feed from https://github.blog/changelog/feed/
• Create tools/utilities/Compare-GitHubOpenAPISpec.ps1 to download the current OpenAPI spec, compare against stored state, and identify changes (new/removed/modified paths)
• Create tools/utilities/Get-ModuleCoverageMap.ps1 to scan src/functions/ and build a map of currently covered API endpoints
• Create tools/utilities/Test-ChangelogRelevance.ps1 to filter changelog entries and spec changes for relevance to the module

State management

• Add logic in the orchestrator to read/write the state file (last RSS timestamp, OpenAPI spec hash) from the changelog-state branch
• Handle first-run scenario where no previous state exists (process all entries from the lookback window, store initial spec hash)

Issue creation via Issue Manager agent

• Create tools/utilities/New-ChangelogIssue.ps1 to generate seed issue content and create issues via the GitHub API
• Implement duplicate detection by searching open issues for matching changelog URLs and endpoint paths
• Apply appropriate labels based on change type (see labels table in technical decisions)
• Add option to assign created issues to Copilot coding agent for the Issue Manager agent to pick up and structure
• Include structured prompt in each seed issue with: changelog entry link, affected endpoints, current coverage status, and suggested scope

Filtering and relevance

• Implement keyword-based filtering for RSS entries (include API-related, exclude UI-only/GHES-only/non-API)
• Implement OpenAPI spec path matching against module coverage map
• Categorize changes as: new endpoint (not covered), modified endpoint (covered), deprecated endpoint (covered), new endpoint (not in scope)

Documentation

• Add inline documentation in the workflow file explaining how the monitoring works
• Document the state branch (changelog-state) and how to reset it
• Add dry-run mode documentation for testing without creating issues

Tests

• Add unit tests for RSS feed parsing logic with mock RSS data
• Add unit tests for OpenAPI spec diff logic with mock before/after specs
• Add unit tests for relevance filtering with sample changelog entries
• Add unit tests for issue body formatting
• Add unit tests for duplicate detection logic