feat(publish): gate auto-publish on releases + publish summary table + docs#160
Open
felickz wants to merge 15 commits into
Open
feat(publish): gate auto-publish on releases + publish summary table + docs#160felickz wants to merge 15 commits into
felickz wants to merge 15 commits into
Conversation
publish.yml now records a per-pack JSON result fragment (published /
up-to-date / failed) from each of the 4 jobs' matrix entries, uploads them
as artifacts, and a new summary job downloads and merges them into a
unified markdown table (languages x pack types) that is:
1. written to the Actions run summary ($GITHUB_STEP_SUMMARY)
2. upserted into the matching GitHub Release body (.release.yml's
version -> vX.Y.Z tag), inside marker comments so "What's Changed"
and other release content is preserved across runs
New scripts:
- .github/scripts/build-publish-summary.sh
- .github/scripts/upsert-release-table.sh
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
The previous form piped the script's stdout through tee and redirected tee's own stdout (not the file write) into GITHUB_STEP_SUMMARY. Combined with 'bash -e' (no pipefail) at the step level, this masked failures and produced an empty summary.md in a real run, upserting empty publish-summary markers into the v0.2.2 release. Switch to plain sequential redirects and add debug output (fragment listing, line/byte counts) to make future failures visible in the step log.
…lease process - publish.yml's push trigger now only fires when .release.yml changes (paths filter), not on every push to main. workflow_dispatch remains as the manual escape hatch for one-off hotfix publishes. - Rewrite CONTRIBUTING.md's Releases & publishing section to match: shipping a pack change now just stages it until the next release cut or a manual dispatch; add a Cutting a release walkthrough for update-release.yml/patch-release-me now that .release.yml's CodeQL Pack Versions location (#158) actually drives every pack's version; document the -alpha.N + workflow_dispatch hotfix convention and note #155 as an accepted one-off exception; note #159 as the recovery path if .release.yml's version is ever hand-edited directly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR tightens the repo’s release/publish mechanics by making batch publishing a deliberate, release-driven action, and by adding automated publish-state reporting to both Actions summaries and GitHub Releases.
Changes:
- Gate
publish.ymlauto-runs to only trigger when.release.ymlchanges (release-cut signal), keepingworkflow_dispatchfor manual publishes. - Capture per-matrix publish outcomes, build a consolidated markdown summary table, and upsert it into the matching GitHub Release body.
- Rewrite the “Releases & publishing” section in
CONTRIBUTING.mdto reflect the new release-cut workflow and hotfix conventions.
Show a summary per file
| File | Description |
|---|---|
CONTRIBUTING.md |
Updates contributor-facing documentation to match the new gated publish/release-cut workflow and hotfix guidance. |
.github/workflows/publish.yml |
Adds .release.yml path gating, records per-matrix publish results, and adds a summary job to post/upsert the publish table. |
.github/scripts/build-publish-summary.sh |
New script that merges JSON result fragments into a markdown publish summary table. |
.github/scripts/upsert-release-table.sh |
New script that inserts/replaces the publish summary block in the corresponding GitHub Release body (creating the release if needed). |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 4/4 changed files
- Comments generated: 7
- Review effort level: Low
- Anchor CURRENT_VERSION extraction to '^version:' (with head -1) in all four publish.yml jobs so a stray 'version' substring elsewhere in a qlpack.yml (e.g. a comment) can't be matched instead of the real field. - upsert-release-table.sh: only take the in-place marker-replacement path when BOTH the start and end marker are present in the existing release body; otherwise append, so a corrupted/partial marker pair can't cause the awk script to silently truncate the rest of the release notes. - CONTRIBUTING.md: grammar fix (find/replaces -> finds and replaces). Verified gh release create --notes-file + --generate-notes together is NOT mutually exclusive in gh 2.96.0 (contrary to a review comment) -- confirmed empirically: the v0.2.3 release this script created has both the publish-summary table (from --notes-file) and the auto-generated 'What's Changed' changelog (from --generate-notes) in its body. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Every publish.yml run now builds and upserts a second table into the matching GitHub Release: for each language, the locked codeql/<lang>-all version (from lib/codeql-pack.lock.yml) versus the version github/codeql itself bundles with the pinned CodeQL CLI (.codeqlversion), read from its own <lang>/ql/lib/qlpack.yml at tag codeql-cli/v<version>. Mismatches are flagged with an actions warning annotation and a table marker, giving a machine-checkable tripwire for the drift risk documented in CONTRIBUTING.md (CI's 'codeql pack install' step is non-resolving, so a forgotten 'codeql pack upgrade <dir>' after a .codeqlversion bump silently pins a language to a stale library version forever). - Add .github/scripts/build-codeql-lib-versions-table.sh - Parameterize upsert-release-table.sh with an optional block-name arg so multiple independent marker-comment blocks can coexist in one release body without clobbering each other - Wire both into publish.yml's summary job - Document the new table and cross-check in CONTRIBUTING.md Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
git-created file lost the exec bit, causing publish.yml's new step to fail with 'Permission denied' (exit 126). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
CONTRIBUTING.md's 'Supported CodeQL versions' table already documents <language>/src/codeql-pack.lock.yml as the source-of-truth lock file (the queries pack CI actually compiles/tests against), not lib. Reading from lib/codeql-pack.lock.yml instead meant the tripwire could miss drift in the src lock, or flag drift that didn't actually affect the compiled queries. Switch the check (and its remediation guidance) to src, per Copilot review feedback on PR #160. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ns table - Discover direct codeql/* dependencies dynamically from each language's src/qlpack.yml instead of hardcoding codeql/<lang>-all, so this also covers codeql/<lang>-queries for C++/C# (which additionally depend on the upstream standard queries pack). - Link every "our locked" version to the exact commit/file/line in this repo (blob/<GITHUB_SHA>/...#L<n>) and every "upstream" version to the exact file/line in github/codeql at the matching codeql-cli/vX tag, so each row can be verified with one click instead of trusting the table. - Rename the section/table to "CodeQL standard library & query pack versions" and update CONTRIBUTING.md references accordingly. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Adds the two workflows needed to close the gap identified while reviewing PR #118 (codeql pack upgrade weekly cron): - detect-codeql-release.yml: weekly (+ workflow_dispatch) tripwire that compares .codeqlversion against github/codeql-cli-binaries' latest release and keeps a single tracking issue open/updated while behind, auto-closing it once caught up. Never opens a PR itself. - update-codeql-version.yml: workflow_dispatch with a codeql_version input. Bumps .codeqlversion, runs codeql pack upgrade <dir> for every pack, and opens a PR via the same GitHub App token pattern as update-release.yml so CI actually runs on it (a GITHUB_TOKEN-authored PR would not trigger downstream workflows). Together these cover detection + mechanical dependency refresh; fixing compile/test breakage from upstream API changes and bumping each pack's own version: still needs a human (or delegated Copilot coding agent) - documented as a 3-step process in CONTRIBUTING.md. Rewrites CONTRIBUTING.md's "Updating the pinned CodeQL CLI/library version" section to describe this new process and adds reference-style links for both new workflows and codeql-cli-binaries. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…ed-check cell Two fixes from Copilot review on PR #160: - publish.yml: only run the "Upsert release table" step on the push (release-cut) trigger, not workflow_dispatch. A manual one-off hotfix publish (see CONTRIBUTING.md) still points .release.yml at the last cut release, so upserting that run's tables into it would overwrite an already-published release's notes with a misleading summary of an unrelated hotfix run. - build-publish-summary.sh: when a pack's version-check step itself fails, previous_version can be empty/null, which rendered as the confusing "publish failed (still ``)". Now shows an explicit "previous version unknown" message in that case. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
src/qlpack.yml and lib/qlpack.yml each declare their own codeql/<lang>-all dependency and resolve it into their own independent codeql-pack.lock.yml. Nothing keeps these two lock files in sync automatically - codeql pack upgrade resolves each pack directory separately, so running it against one and not the other silently lets them drift. The standard-library-versions table previously only checked src as a 'coarse signal', which meant a stale lib lock could go undetected while the table showed all green. Now checks both src and lib for every language (ext/ext-library-sources are still out of scope: they pin via extensionTargets, not dependencies, so CodeQL never resolves a locked version for them). Adds a Pack column to the table to distinguish rows. Also updates CONTRIBUTING.md's Supported CodeQL versions section, which similarly implied a single lock file was the source of truth per language. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
CONTRIBUTING.md said publish.yml is organized as four jobs, but it also has a fifth 'summary' job (needs: [queries, library, extensions, library_sources_extensions], if: always()) that aggregates results into the publish-summary and CodeQL lib-versions tables and upserts them into the Release notes. Clarify the doc to describe all five. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
…oesn't exist yet All four publish jobs (queries/library/extensions/library_sources_extensions) read the currently-published version via 'gh api .../versions'. run: steps default to bash -e, so a 404 (package never published, e.g. a brand-new language/pack) aborted the step and failed the job before it could ever publish that pack for the first time. Move '|| true' inside the command substitution so a fetch failure just leaves PUBLISHED_VERSION empty (correctly differing from CURRENT_VERSION, triggering a first publish) instead of killing the step under set -e. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Comment on lines
+63
to
+70
| BODY="A newer CodeQL CLI release is available upstream. | ||
|
|
||
| - Pinned (\`.codeqlversion\`): [\`v${PINNED}\`](https://github.com/github/codeql-cli-binaries/releases/tag/v${PINNED}) | ||
| - Latest upstream: [\`v${LATEST}\`](https://github.com/github/codeql-cli-binaries/releases/tag/v${LATEST}) | ||
|
|
||
| To start the update, run the [\"Update CodeQL CLI Version\"](https://github.com/${REPO}/actions/workflows/update-codeql-version.yml) workflow (\`workflow_dispatch\`) with \`codeql_version: ${LATEST}\`. See [CONTRIBUTING.md: Updating the pinned CodeQL CLI/library version](https://github.com/${REPO}/blob/main/CONTRIBUTING.md#updating-the-pinned-codeql-clilibrary-version) for the full process. | ||
|
|
||
| This issue is kept up to date automatically by the \"Detect New CodeQL CLI Release\" workflow and will auto-close once \`.codeqlversion\` catches up." |
Contributor
Author
There was a problem hiding this comment.
Confirmed real - the leading whitespace on the BODY continuation lines will render as an indented code block in the issue. This is a new (not-yet-live) workflow that can only be exercised via workflow_dispatch after this PR merges, so rather than adding another commit/CI cycle here, I've filed #162 to fix it as part of the first live test of this workflow post-merge.
Comment on lines
+22
to
+26
| update-codeql-version: | ||
| runs-on: ubuntu-latest | ||
| permissions: | ||
| contents: read # PR creation uses a scoped GitHub App token (SECLABS_APP_ID/SECLABS_APP_KEY), not GITHUB_TOKEN | ||
|
|
Contributor
Author
There was a problem hiding this comment.
Confirmed - ci.yml explicitly grants packages: read for the same kind of codeql pack resolution, and this workflow's permissions block only has contents: read. Filed #162 to add packages: read and verify with a live dispatch run post-merge, rather than adding another commit/CI cycle to this already-green PR.
👍
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 this does
This is the follow-through on the release-process work from #158/#155/#159 — closes the architectural gap where any single push to
maincould silently auto-publish one pack ahead of the rest of the repo (exactly what happened with #155).1. Gate auto-publish on
.release.ymlchangespublish.yml'spushtrigger now only fires when.release.ymlitself changes (paths:filter), instead of on every push tomain. Cutting a release viaupdate-release.yml(which bumps.release.yml+ every pack's version together) is now the single deliberate "go" signal for a real batch publish.workflow_dispatchremains as the manual escape hatch for urgent one-off hotfix publishes.2. Publish summary table
Every
publish.ymlrun now posts a markdown table (language × pack type → published/up-to-date/failed version, with 🆕 marking anything actually republished) to:New scripts:
.github/scripts/build-publish-summary.sh,.github/scripts/upsert-release-table.sh. Verified end-to-end against the realv0.2.2andv0.2.3releases.3. CONTRIBUTING.md rewrite
The "Releases & publishing" section now documents the actual current mechanics:
update-release.yml/patch-release-me, including a warning against hand-editing.release.yml's version directly (see chore: bump remaining packs to 0.2.3 to match .release.yml #159 for what happens when you do)-alpha.N+workflow_dispatchconvention for one-off hotfixes, with fix(java): remove duplicate codeql-java-extensions dependency causing fatal analysis crash #155 called out as an accepted exception under the old rulesCo-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com