Release/publish process improvements: version-bump safeguard, CodeQL release detection, and a published-version inventory#156
Draft
felickz wants to merge 6 commits into
Draft
Conversation
- Document how publish.yml decides what to publish (per-pack version diff vs GHCR) and that it only runs automatically on merge to main for packs whose version was bumped. - Explain that GitHub Releases / .release.yml / update-release.yml are a decoupled, manually-curated changelog and are NOT required for, or tied to, package publishing. - Document where to find what's published now (GHCR) vs what's about to publish (qlpack.yml on main), since no inventory exists. - Add a "Keeping CodeQL versions current" subsection describing today's manual CLI-update process and linking open PR #118.
Adds a new advisory (non-blocking) CI job, version-bump-check, that
complements pr-suites-packs.sh's existing "version was bumped" comment:
- pr-suites-packs.sh already comments when qlpack.yml/lock file changed
AND the version differs from published (a bump was made).
- This new check covers the opposite, previously-silent gap: files
changed under <lang>/{src,lib,ext,ext-library-sources}/** but the
pack's version still matches what's already published on GHCR, so
publish.yml will not ship the change on merge.
Deliberately advisory rather than blocking: the repo's actual practice
sometimes splits a content change and its version bump across
sequential PRs (see #123 -> #124), so a hard-blocking check would
break that established workflow.
Adds detect-codeql-release.yml, a weekly scheduled workflow (+ workflow_dispatch) that compares github/codeql-cli-binaries' latest release against .codeqlversion and, on drift, opens a tracking issue (idempotent - skipped if one is already open for that version) with the manual update checklist from CONTRIBUTING.md's "Keeping CodeQL versions current" section. Nothing in the repo previously watched for new upstream CodeQL releases at all - a maintainer had to notice by hand. This only automates detection + filing the issue; bumping .codeqlversion, running `codeql pack upgrade`, fixing any resulting compile/test breakage, and bumping affected pack versions remain manual follow-up steps for a maintainer or contributor to pick up (deliberately not automated further in this change).
Adds generate-version-inventory.sh (queries GHCR for every pack's published version, alongside the local qlpack.yml version) and a weekly scheduled workflow, publish-version-inventory.yml, that regenerates PACKAGE_VERSIONS.md and opens/updates a single PR when it drifts (reuses one stable branch, force-pushed, rather than piling up a new PR every week since the file is fully machine-generated). Today there's no in-repo inventory of what's published - answering "what's live?" means paging through the GHCR Packages UI or grepping 20+ qlpack.yml files by hand. PACKAGE_VERSIONS.md itself isn't included in this commit: it will be created by the first run of this workflow after merge (scheduled, or triggered on demand via workflow_dispatch).
…entory automation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves the repo’s release/publish operational workflow by documenting the (currently decoupled) release vs. GHCR publishing mechanics, adding PR-time safeguards around pack version bumps, and introducing scheduled automation to detect upstream CodeQL CLI releases and to maintain an inventory of published pack versions.
Changes:
- Documents how GHCR publishing is triggered and why per-pack
qlpack.ymlversion bumps are required to actually ship changes. - Adds CI advisory automation to flag pack-content changes that won’t publish due to missing version bumps.
- Adds scheduled workflows/scripts to (a) detect upstream CodeQL CLI releases and file a tracking issue, and (b) generate/update a
PACKAGE_VERSIONS.mdinventory via an automated PR.
Show a summary per file
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds a detailed “Releases & publishing” section and documents the new automation. |
| .github/workflows/publish-version-inventory.yml | New scheduled workflow to regenerate PACKAGE_VERSIONS.md and open/update a single PR. |
| .github/workflows/detect-codeql-release.yml | New scheduled workflow to run CodeQL CLI release detection script. |
| .github/workflows/ci.yml | Adds the version-bump-check advisory job to comment on PRs when a version bump appears missing. |
| .github/scripts/pr-version-bump-check.sh | New script to detect pack-directory changes without a corresponding published-version bump. |
| .github/scripts/generate-version-inventory.sh | New script to generate a “published vs on-main” pack version table. |
| .github/scripts/check-codeql-release.sh | New script to detect upstream CodeQL CLI releases and open an idempotent tracking issue. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 4
- Review effort level: Low
- pr-version-bump-check.sh: only check ext/ext-library-sources for csharp/java, matching publish.yml's actual matrix. go/ext and python/ext exist but aren't published by publish.yml (see #144), so telling contributors a version bump would ship them was misleading. - check-codeql-release.sh: replace broken `../blob/main/...` relative links in the generated issue body with full https://github.com/... URLs (derived from $GITHUB_REPOSITORY), since GitHub issue markdown resolves relative links against the issue's own path, not the repo root. - ci.yml: rename the advisory job from "Check pack version was bumped" to "Warn if pack version bump is missing" so the Actions UI doesn't imply the version was actually bumped when this job runs/passes. Co-authored-by: Copilot App <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.
Why
Prompted by a deep-dive into how this repo releases and publishes packages (context: #117, #123, #124, #126, #118). Key findings that motivate this PR:
.release.yml/update-release.ymldrive a repo-wide changelog version (currently stuck at0.2.0, one release behind reality). Actual publishing to GHCR is driven entirely bypublish.ymlcomparing each pack'sqlpack.ymlversion:against what's on GHCR, on every push tomain.version:is also bumped — confirmed by the Update dependencies to packs shipped with 2.21.1 #124 (CodeQL 2.21.1 update, no version bumps) → later ad-hoc per-language bump pattern, and by fix(java): remove duplicate codeql-java-extensions dependency causing fatal analysis crash #155 (a real cross-pack version-pin bug)..codeqlversion→codeql pack upgrade→ fix breakage → bump pack versions" chain is 100% manual today. Feat: Add Automatic weekly CodeQL Pack Updating Job #118 (open, unmerged) only automates the mechanicalcodeql pack upgraderefresh — not detection, not breakage fixes, not version bumps.qlpack.ymlfiles.What this PR does
Five focused commits, each independently reviewable:
docs: clarify release/publish mechanics in CONTRIBUTING.md— new "Releases & publishing" section explaining the publish trigger, the manual version-bump requirement, what GitHub Releases are actually for (and that they're stale/decoupled), and the manual CodeQL-update process.ci: warn when pack content changes without a version bump— new advisory (non-blocking)version-bump-checkCI job +pr-version-bump-check.sh. Complementspr-suites-packs.sh's existing "version was bumped" comment by covering the opposite, previously-silent gap: content changed but the version still matches what's published, sopublish.ymlwon't ship it. Non-blocking on purpose, since content changes and their version bump are sometimes intentionally split across sequential PRs (Java: remove SpringBootActuators query #123 → Update dependencies to packs shipped with 2.21.1 #124).ci: detect new upstream CodeQL CLI releases weekly— newdetect-codeql-release.ymlscheduled workflow that comparesgithub/codeql-cli-binaries's latest release to.codeqlversionand opens an idempotent tracking issue with the manual update checklist when they drift. (Verified live: latest upstream is currentlyv2.25.6vs. this repo's pinnedv2.21.1— this would immediately open a real issue once merged.) This only automates detection + filing the issue; bumping.codeqlversion, runningcodeql pack upgrade, fixing breakage, and bumping pack versions remain manual steps for whoever picks up the issue — deliberately not automated further here.ci: generate a published-version inventory (PACKAGE_VERSIONS.md)— newgenerate-version-inventory.sh+ weeklypublish-version-inventory.ymlthat regeneratesPACKAGE_VERSIONS.md(published vs. on-mainversion per pack) and opens/updates a single PR when it drifts.PACKAGE_VERSIONS.mditself isn't included in this PR — it'll be created by the first workflow run after merge (scheduled, orworkflow_dispatchon demand).docs: document the new version-bump-check, release-detection, and inventory automation— wires the above three into CONTRIBUTING.md so the docs and the automation stay consistent.All new shell scripts follow the existing conventions in
.github/scripts/(same idempotentgh pr comment/gh issue listpatterns, samegh api /orgs/githubsecuritylab/packages/container/<pkg>/versionslookup already used bypr-suites-packs.shandpublish.yml). All new/edited YAML validated with a YAML parser; all new shell scripts syntax-checked.Explicitly NOT done in this PR (recommendations only, need maintainer input)
publish.yml's ext/library-sources jobs to python/go) look like they should be reviewed/merged soon. Left alone here since closing/merging other PRs needs an explicit maintainer decision, not a unilateral change bundled into this one..release.yml/GitHub Releases — currently stale and decoupled from real publishing. Worth a maintainer decision on whether to wire it to real pack versions, keep it as a purely human-curated changelog, or retire it.GITHUB_TOKEN), and the harder part of a CLI bump (fixing compile/test breakage from upstream API changes, per Update dependencies to packs shipped with 2.21.1 #124) needs human judgment either way. Landed on "auto-detect + file an actionable issue" (commit 3) as the right scope for now; a maintainer can always assign that issue to whoever/whatever they want.Post-merge follow-ups
publish-version-inventory.ymlonce viaworkflow_dispatchto generate the initialPACKAGE_VERSIONS.md(or just wait for Monday's schedule).detect-codeql-release.yml's first run will likely open a real "CodeQL CLI v2.25.6 is available" issue immediately, given the current drift.