Skip to content

Commit ec08944

Browse files
data-douserdata-douser
committed
Publish to npmjs.org with OIDC trusted publishing
- Rename package to unscoped `codeql-development-mcp-server` - Switch from GitHub Packages to public npmjs.org registry - Use OIDC trusted publishing (no tokens, auto-provenance) - Make release.yml the sole dispatch entry point with configurable publish_npm, publish_codeql_packs, and create_github_release flags - Remove workflow_dispatch from child workflows (release-npm, release-codeql, release-tag) to comply with OIDC validation - Fix release-tag.yml: wire tag_sha output to final-sha step, guard git add -A against staging CodeQL artifacts - Add setup-packs.sh script (shipped in npm package) to install CodeQL pack dependencies from bundled lock files - Update all docs, tests, and SKILL.md references
1 parent 7698aa9 commit ec08944

12 files changed

Lines changed: 253 additions & 116 deletions

File tree

‎.github/skills/validate-ql-mcp-server-tools-queries/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -336,7 +336,7 @@ When the STDIO transport receives an immediate EOF on stdin (e.g., via `</dev/nu
336336

337337
### npm Package Includes Tool Query Source Packs
338338

339-
The published npm package (`@advanced-security/codeql-development-mcp-server`) bundles all tool query source packs under `ql/*/tools/src/`. These are the same `.ql`, `.qll`, `.md`, `codeql-pack.yml`, and `codeql-pack.lock.yml` files — but **never** compiled `.qlx` bytecode (excluded by `server/.npmignore`).
339+
The published npm package (`codeql-development-mcp-server`) bundles all tool query source packs under `ql/*/tools/src/`. These are the same `.ql`, `.qll`, `.md`, `codeql-pack.yml`, and `codeql-pack.lock.yml` files — but **never** compiled `.qlx` bytecode (excluded by `server/.npmignore`).
340340

341341
## Success Criteria
342342

‎.github/workflows/release-codeql.yml‎

Lines changed: 6 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,17 +19,12 @@ on:
1919
version:
2020
description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
2121
value: ${{ jobs.publish-codeql-packs.outputs.version }}
22-
workflow_dispatch:
23-
inputs:
24-
publish_codeql_packs:
25-
default: true
26-
description: 'Publish CodeQL tool query packs to GHCR. Disable for pre-release or re-run scenarios where packs already exist.'
27-
required: false
28-
type: boolean
29-
version:
30-
description: 'Release version tag (e.g., vX.Y.Z). Must start with "v". Tag must already exist.'
31-
required: true
32-
type: string
22+
23+
# Note: This workflow is called exclusively via workflow_call from release.yml.
24+
# It does NOT have a workflow_dispatch trigger to keep release.yml as the single
25+
# entry point for all release operations. To re-publish CodeQL packs standalone,
26+
# use workflow_dispatch on release.yml with publish_npm=false and
27+
# create_github_release=false.
3328

3429
permissions:
3530
contents: read

‎.github/workflows/release-npm.yml‎

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,14 @@ on:
1414
version:
1515
description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
1616
value: ${{ jobs.publish-npm.outputs.version }}
17-
workflow_dispatch:
18-
inputs:
19-
version:
20-
description: 'Release version tag (e.g., vX.Y.Z). Must start with "v". Tag must already exist.'
21-
required: true
22-
type: string
17+
18+
# Note: This workflow is called exclusively via workflow_call from release.yml.
19+
# It does NOT have a workflow_dispatch trigger because npm Trusted Publishing
20+
# validates the *calling* workflow filename for OIDC. The trusted publisher on
21+
# npmjs.com is configured with workflow "release.yml" and environment
22+
# "release-npm". Direct dispatch would present "release-npm.yml" as the workflow
23+
# name, causing OIDC authentication to fail. To re-publish the npm package
24+
# standalone, use workflow_dispatch on release.yml instead.
2325

2426
permissions:
2527
contents: read
@@ -33,7 +35,7 @@ jobs:
3335

3436
permissions:
3537
contents: read
36-
packages: write
38+
id-token: write
3739

3840
outputs:
3941
release_name: ${{ steps.version.outputs.release_name }}
@@ -61,8 +63,7 @@ jobs:
6163
with:
6264
cache: 'npm'
6365
node-version-file: '.node-version'
64-
registry-url: 'https://npm.pkg.github.com'
65-
scope: '@advanced-security'
66+
registry-url: 'https://registry.npmjs.org'
6667

6768
- name: npm - Install dependencies
6869
run: npm ci --include=optional
@@ -72,12 +73,10 @@ jobs:
7273

7374
- name: npm - Publish npm package
7475
working-directory: server
75-
env:
76-
NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
7776
run: |
78-
echo "Publishing @advanced-security/codeql-development-mcp-server to GitHub Packages..."
77+
echo "Publishing codeql-development-mcp-server to npmjs.org via OIDC trusted publishing..."
7978
npm publish
80-
echo "✅ Published npm package to GitHub Packages"
79+
echo "✅ Published npm package to npmjs.org (with provenance)"
8180
8281
- name: npm - Upload release build artifact
8382
uses: actions/upload-artifact@v6
@@ -100,7 +99,7 @@ jobs:
10099
echo "" >> $GITHUB_STEP_SUMMARY
101100
echo "| Detail | Value |" >> $GITHUB_STEP_SUMMARY
102101
echo "| ------ | ----- |" >> $GITHUB_STEP_SUMMARY
103-
echo "| Package | \`@advanced-security/codeql-development-mcp-server\` |" >> $GITHUB_STEP_SUMMARY
102+
echo "| Package | \`codeql-development-mcp-server\` |" >> $GITHUB_STEP_SUMMARY
104103
echo "| Version | ${RELEASE_NAME} |" >> $GITHUB_STEP_SUMMARY
105-
echo "| Registry | GitHub Packages |" >> $GITHUB_STEP_SUMMARY
104+
echo "| Registry | npmjs.org |" >> $GITHUB_STEP_SUMMARY
106105
echo "| Tag | ${VERSION} |" >> $GITHUB_STEP_SUMMARY

‎.github/workflows/release-tag.yml‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,10 @@ on:
1717
version:
1818
description: 'The full version string with "v" prefix (e.g., vX.Y.Z)'
1919
value: ${{ jobs.create-tag.outputs.version }}
20-
workflow_dispatch:
21-
inputs:
22-
version:
23-
description: 'Release version (e.g., vX.Y.Z). Must start with "v".'
24-
required: true
25-
type: string
20+
21+
# Note: This workflow is called exclusively via workflow_call from release.yml.
22+
# It does NOT have a workflow_dispatch trigger to keep release.yml as the single
23+
# entry point for all release operations.
2624

2725
permissions:
2826
contents: read
@@ -39,7 +37,7 @@ jobs:
3937

4038
outputs:
4139
release_name: ${{ steps.version.outputs.release_name }}
42-
tag_sha: ${{ steps.create-tag.outputs.tag_sha }}
40+
tag_sha: ${{ steps.final-sha.outputs.tag_sha }}
4341
version: ${{ steps.version.outputs.version }}
4442

4543
steps:
@@ -129,6 +127,9 @@ jobs:
129127
130128
# Stage version-bearing files and lockfile changes
131129
git add -A
130+
# Ensure CodeQL-generated artifacts are not staged for commit
131+
git restore --staged .codeql || true
132+
git restore --staged '*.qlx' || true
132133
133134
# Check if there are changes to commit
134135
if git diff --cached --quiet; then

‎.github/workflows/release.yml‎

Lines changed: 40 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,21 @@ on:
66
- 'v*'
77
workflow_dispatch:
88
inputs:
9+
create_github_release:
10+
default: true
11+
description: 'Create GitHub Release with distribution archive and CodeQL pack bundles. Disable to only publish packages without creating a release.'
12+
required: false
13+
type: boolean
914
publish_codeql_packs:
1015
default: true
1116
description: 'Publish CodeQL tool query packs to GHCR. Disable for pre-release or re-run scenarios where packs already exist.'
1217
required: false
1318
type: boolean
19+
publish_npm:
20+
default: true
21+
description: 'Publish npm package to npmjs.org via OIDC trusted publishing. Disable for pre-release or re-run scenarios where the npm package already exists.'
22+
required: false
23+
type: boolean
1424
version:
1525
description: 'Release version (e.g., vX.Y.Z). Must start with "v".'
1626
required: true
@@ -32,7 +42,9 @@ jobs:
3242
runs-on: ubuntu-latest
3343

3444
outputs:
45+
create_github_release: ${{ steps.resolve.outputs.create_github_release }}
3546
publish_codeql_packs: ${{ steps.resolve.outputs.publish_codeql_packs }}
47+
publish_npm: ${{ steps.resolve.outputs.publish_npm }}
3648
release_name: ${{ steps.resolve.outputs.release_name }}
3749
version: ${{ steps.resolve.outputs.version }}
3850

@@ -52,16 +64,22 @@ jobs:
5264
exit 1
5365
fi
5466
55-
# Resolve publish_codeql_packs (default true for tag pushes)
67+
# Resolve publish flags (default true for tag pushes)
5668
if [ "${{ github.event_name }}" == "workflow_dispatch" ]; then
69+
CREATE_RELEASE="${{ github.event.inputs.create_github_release }}"
5770
PUBLISH_PACKS="${{ github.event.inputs.publish_codeql_packs }}"
71+
PUBLISH_NPM="${{ github.event.inputs.publish_npm }}"
5872
else
73+
CREATE_RELEASE="true"
5974
PUBLISH_PACKS="true"
75+
PUBLISH_NPM="true"
6076
fi
6177
6278
echo "version=${VERSION}" >> $GITHUB_OUTPUT
6379
echo "release_name=${VERSION#v}" >> $GITHUB_OUTPUT
80+
echo "create_github_release=${CREATE_RELEASE}" >> $GITHUB_OUTPUT
6481
echo "publish_codeql_packs=${PUBLISH_PACKS}" >> $GITHUB_OUTPUT
82+
echo "publish_npm=${PUBLISH_NPM}" >> $GITHUB_OUTPUT
6583
6684
# ─────────────────────────────────────────────────────────────────────────────
6785
# Step 2: Ensure the release tag exists
@@ -83,15 +101,20 @@ jobs:
83101
# Step 3a: Build and publish the npm package
84102
#
85103
# Checks out the clean tag (no CodeQL pack artifacts), builds with `npm ci`,
86-
# and publishes to GitHub Packages. Runs in parallel with CodeQL pack
87-
# publishing since they are independent.
104+
# and publishes to npmjs.org via OIDC trusted publishing. Runs in parallel
105+
# with CodeQL pack publishing since they are independent.
106+
#
107+
# The trusted publisher on npmjs.com is configured with workflow "release.yml"
108+
# and environment "release-npm". The id-token:write permission is required for
109+
# OIDC authentication — no npm tokens are used.
88110
# ─────────────────────────────────────────────────────────────────────────────
89111
publish-npm:
90112
name: Publish npm Package
113+
if: needs.resolve-version.outputs.publish_npm == 'true'
91114
needs: [resolve-version, ensure-tag]
92115
permissions:
93116
contents: read
94-
packages: write
117+
id-token: write
95118
uses: ./.github/workflows/release-npm.yml
96119
with:
97120
version: ${{ needs.resolve-version.outputs.version }}
@@ -104,6 +127,7 @@ jobs:
104127
# ─────────────────────────────────────────────────────────────────────────────
105128
publish-codeql:
106129
name: Publish CodeQL Packs
130+
if: needs.resolve-version.outputs.publish_codeql_packs == 'true'
107131
needs: [resolve-version, ensure-tag]
108132
permissions:
109133
contents: read
@@ -118,11 +142,18 @@ jobs:
118142
#
119143
# Downloads the clean build artifact (from npm workflow) and pack bundles
120144
# (from CodeQL workflow), assembles the distribution archive, and creates the
121-
# GitHub Release.
145+
# GitHub Release. Only runs for full releases (all publish steps enabled and
146+
# create_github_release is true). Partial workflows (e.g., re-publishing only
147+
# npm or only CodeQL packs) skip this step.
122148
# ─────────────────────────────────────────────────────────────────────────────
123149
create-release:
124150
name: Create GitHub Release
125-
needs: [resolve-version, publish-npm, publish-codeql]
151+
if: >-
152+
always() && !failure() && !cancelled()
153+
&& needs.resolve-version.outputs.create_github_release == 'true'
154+
&& needs.resolve-version.outputs.publish_npm == 'true'
155+
&& needs.resolve-version.outputs.publish_codeql_packs == 'true'
156+
needs: [resolve-version, ensure-tag, publish-npm, publish-codeql]
126157
runs-on: ubuntu-latest
127158

128159
permissions:
@@ -162,11 +193,6 @@ jobs:
162193
# Remove test and examples directories from ql folders (only keep src)
163194
find dist-package/server/ql -type d \( -name "test" -o -name "examples" \) -prune -exec rm -rf {} \;
164195
165-
- name: Release - Setup Node.js
166-
uses: actions/setup-node@v6
167-
with:
168-
node-version-file: '.node-version'
169-
170196
- name: Release - Install production dependencies
171197
working-directory: dist-package/server
172198
run: npm install --omit=dev --include=optional
@@ -194,22 +220,17 @@ jobs:
194220
run: |
195221
VERSION="${{ needs.resolve-version.outputs.version }}"
196222
RELEASE_NAME="${{ needs.resolve-version.outputs.release_name }}"
197-
PUBLISH_PACKS="${{ needs.resolve-version.outputs.publish_codeql_packs }}"
198223
echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
199224
echo "" >> $GITHUB_STEP_SUMMARY
200225
echo "| Step | Status |" >> $GITHUB_STEP_SUMMARY
201226
echo "| ---- | ------ |" >> $GITHUB_STEP_SUMMARY
202227
echo "| Tag | ✅ ${VERSION} |" >> $GITHUB_STEP_SUMMARY
203228
echo "| Server build | ✅ Success |" >> $GITHUB_STEP_SUMMARY
204229
echo "| Version validation | ✅ All files match ${RELEASE_NAME} |" >> $GITHUB_STEP_SUMMARY
205-
if [ "${PUBLISH_PACKS}" != "true" ]; then
206-
echo "| CodeQL pack publish | ⏭️ Skipped (disabled via input) |" >> $GITHUB_STEP_SUMMARY
207-
else
208-
echo "| CodeQL pack publish | ✅ Published to GHCR |" >> $GITHUB_STEP_SUMMARY
209-
fi
210-
echo "| npm package | ✅ Published to GitHub Packages |" >> $GITHUB_STEP_SUMMARY
230+
echo "| npm publish | ✅ Published to npmjs.org |" >> $GITHUB_STEP_SUMMARY
231+
echo "| CodeQL pack publish | ✅ Published to GHCR |" >> $GITHUB_STEP_SUMMARY
211232
echo "| Distribution archive | ✅ Created |" >> $GITHUB_STEP_SUMMARY
212-
echo "| CodeQL pack bundles | ✅ Bundled |" >> $GITHUB_STEP_SUMMARY
233+
echo "| GitHub Release | ✅ Created |" >> $GITHUB_STEP_SUMMARY
213234
echo "" >> $GITHUB_STEP_SUMMARY
214235
echo "### Package Contents" >> $GITHUB_STEP_SUMMARY
215236
echo "- \`server/dist/\` - Bundled JavaScript output" >> $GITHUB_STEP_SUMMARY

‎README.md‎

Lines changed: 4 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,21 +57,17 @@ Please note that this project is released with a [Contributor Code of Conduct](C
5757

5858
### Install via npm (recommended)
5959

60-
No repository clone needed — install from [GitHub Packages](https://github.com/advanced-security/codeql-development-mcp-server/pkgs/npm/codeql-development-mcp-server):
60+
No repository clone needed — install from [npmjs.org](https://www.npmjs.com/package/codeql-development-mcp-server):
6161

6262
```bash
63-
# One-time: route @advanced-security scope to GitHub Packages and authenticate
64-
npm config set @advanced-security:registry https://npm.pkg.github.com
65-
npm login --registry=https://npm.pkg.github.com
66-
6763
# Install globally
68-
npm install -g @advanced-security/codeql-development-mcp-server
64+
npm install -g codeql-development-mcp-server
6965
```
7066

7167
Or run on-demand without installing globally:
7268

7369
```bash
74-
npx -y @advanced-security/codeql-development-mcp-server
70+
npx -y codeql-development-mcp-server
7571
```
7672

7773
### VS Code Configuration
@@ -89,7 +85,7 @@ Add to your `mcp.json` file:
8985
"servers": {
9086
"ql-mcp": {
9187
"command": "npx",
92-
"args": ["-y", "@advanced-security/codeql-development-mcp-server"],
88+
"args": ["-y", "codeql-development-mcp-server"],
9389
"type": "stdio"
9490
}
9591
}

‎docs/getting-started.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -12,23 +12,24 @@ This guide covers installation, configuration, and usage of the CodeQL Developme
1212

1313
### From npm (recommended)
1414

15-
The package is published to [GitHub Packages](https://github.com/advanced-security/codeql-development-mcp-server/pkgs/npm/codeql-development-mcp-server). Configure npm once, then install:
15+
The package is published to the [public npm registry](https://www.npmjs.com/package/codeql-development-mcp-server). No authentication or special configuration is needed:
1616

1717
```bash
18-
# One-time: route @advanced-security scope to GitHub Packages and authenticate
19-
npm config set @advanced-security:registry https://npm.pkg.github.com
20-
npm login --registry=https://npm.pkg.github.com
21-
2218
# Install globally
23-
npm install -g @advanced-security/codeql-development-mcp-server
19+
npm install -g codeql-development-mcp-server
20+
21+
# Install CodeQL pack dependencies (required on first use)
22+
codeql-development-mcp-server-setup-packs
2423
```
2524

2625
Or use `npx` to run without a global install:
2726

2827
```bash
29-
npx -y @advanced-security/codeql-development-mcp-server
28+
npx -y codeql-development-mcp-server
3029
```
3130

31+
> **Note:** The npm package bundles the tool query source packs (`.ql` files and lock files), but their CodeQL library dependencies (e.g., `codeql/javascript-all`) must be fetched from GHCR on first use. Run `codeql-development-mcp-server-setup-packs` once after installing to download them (`~/.codeql/packages/`). If you skip this step, the `codeql_pack_install` MCP tool can install dependencies on demand for individual packs.
32+
3233
### From GitHub Releases
3334

3435
1. Download the latest release from [Releases](https://github.com/advanced-security/codeql-development-mcp-server/releases)
@@ -59,7 +60,7 @@ Add to your `mcp.json` file:
5960
"servers": {
6061
"ql-mcp": {
6162
"command": "npx",
62-
"args": ["-y", "@advanced-security/codeql-development-mcp-server"],
63+
"args": ["-y", "codeql-development-mcp-server"],
6364
"type": "stdio"
6465
}
6566
}
@@ -98,6 +99,7 @@ Add to your `mcp.json` file:
9899

99100
## Troubleshooting
100101

102+
- **Tool query errors (e.g., PrintAST fails)**: Run `codeql-development-mcp-server-setup-packs` to install CodeQL pack dependencies
101103
- **Server not listed**: Verify absolute path in `mcp.json`, restart VS Code
102104
- **CodeQL errors**: Run `codeql --version` to confirm CLI is installed
103105
- **Permission denied**: Check file permissions on server directory

0 commit comments

Comments
 (0)