Overhaul plugin docs - #261
Merged
Merged
Conversation
JoyceZhu
commented
Aug 21, 2026
JoyceZhu
commented
Contributor
- new issue template for allowlisting third-party issues from NPM
- plugin documentation reorganized and rewritten to organize information about all plugins vs. NPM plugins only vs. local plugins only
- new issue template for allowlisting third-party issues from NPM - plugin documentation reorganized and rewritten to organize information about all plugins vs. NPM plugins only vs. local plugins only
JoyceZhu
requested review from
kendallgassner
and
a balanced review from Copilot
August 21, 2026 06:57
JoyceZhu
enabled auto-merge
August 21, 2026 06:57
Contributor
There was a problem hiding this comment.
Pull request overview
Reorganizes plugin documentation and introduces an issue form for requesting third-party NPM plugin allowlisting.
Changes:
- Separates guidance for NPM-hosted and local plugins.
- Adds an allowlisting request issue form.
Show a summary per file
| File | Description |
|---|---|
PLUGINS.md |
Reworks plugin creation and loading guidance. |
.github/ISSUE_TEMPLATE/allowlist-npm-plugin-request.yml |
Adds the allowlisting request form. |
Review details
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Suppressed comments (2)
PLUGINS.md:36
- This relative URL resolves to a nonexistent repository path instead of the heading in this document, so the navigation link returns a 404. Use the heading fragment here.
To then enable an NPM plugin in the `scans` input, follow the instructions in the [loading plugins from NPM](./loading-plugins-from-npm-packages) section.
.github/ISSUE_TEMPLATE/allowlist-npm-plugin-request.yml:10
- This textarea also lacks the unique
idrequired for non-Markdown GitHub Issue Form elements, so the template will fail schema validation.
- type: textarea
- Files reviewed: 2/2 changed files
- Comments generated: 7
- Review effort level: Balanced
Comment on lines
+10
to
+13
| ### Plugin folder structure for all plugins | ||
|
|
||
| Plugins are dynamically loaded by the scanner when it runs. The scanner will look into the `./.github` folder in your repo (where you run the workflow from) and search for a `scanner-plugins` folder. If it finds it, it will assume each folder under that is a plugin, and attempt to load the `index.ts` (first) or `index.js` (second) file inside it. Once loaded, the scanner will invoke the exported default function from the `index.js/index.ts` file. | ||
| - Each plugin should have one `index.ts` OR `index.js` file inside its folder. | ||
| - The `index.ts/index.js` file must export a `name` field. This is the name used to pass to the `scans` input. So if the plugin exports a name value of `my-custom-plugin` and we pass the following to the scanner action inputs: `scans: ['my-custom-plugin']`, it would cause the scanner to only run that plugin. |
| Plugins are dynamically loaded by the scanner when it runs. The scanner will look into the `./.github` folder in your repo (where you run the workflow from) and search for a `scanner-plugins` folder. If it finds it, it will assume each folder under that is a plugin, and attempt to load the `index.ts` (first) or `index.js` (second) file inside it. Once loaded, the scanner will invoke the exported default function from the `index.js/index.ts` file. | ||
| - Each plugin should have one `index.ts` OR `index.js` file inside its folder. | ||
| - The `index.ts/index.js` file must export a `name` field. This is the name used to pass to the `scans` input. So if the plugin exports a name value of `my-custom-plugin` and we pass the following to the scanner action inputs: `scans: ['my-custom-plugin']`, it would cause the scanner to only run that plugin. | ||
| - The `index.ts/index.js` file must export a default function (see [below](./default-function-api)). This is the function that the scanner uses to run the plugin. This can be an async function. |
| - The `index.ts/index.js` file must export a `name` field. This is the name used to pass to the `scans` input. So if the plugin exports a name value of `my-custom-plugin` and we pass the following to the scanner action inputs: `scans: ['my-custom-plugin']`, it would cause the scanner to only run that plugin. | ||
| - The `index.ts/index.js` file must export a default function. This is the function that the scanner uses to run the plugin. This can be an async function. | ||
| - In your workflow file, before the scanner step, add `- uses: actions/checkout@v6` (or whatever the current version is). This allows the current repository's files (where your custom plugin's file exists) to be read: | ||
| Once the public URL is live, please fill out [this issue template](./.github/ISSUE_TEMPLATE/allowlist-npm-plugin-request.yml) so we can allowlist your plugin in future versions of the scanner. |
| description: Fill out the details to request allowlisting your third party plugin hosted on NPM in the scanner. | ||
| labels: 'allowlist-plugin-request' | ||
| body: | ||
| - type: input |
abdulahmad307
approved these changes
Aug 21, 2026
abdulahmad307
left a comment
abdulahmad307
left a comment
Contributor
There was a problem hiding this comment.
lgtm (aside from the copilot comments)
Contributor
|
oh lol - i didnt realize automerge was on. i guess we can fix the copilot warnings in a second PR |
edsummersnc
reviewed
Aug 21, 2026
edsummersnc
left a comment
edsummersnc
left a comment
There was a problem hiding this comment.
It would be good to document the reason why there is a plugin allow-list and also the summary of our plugin review/approval process. IOW:
- Why are we gate-keeping the plugin list?
- What reviews are we going to perform after someone submits an npm plguin? They need to know this so they can perform the reviews themselves before submitting the issue.
- What are the conditions for approval and rejection?
Consider adding a field to the issue template to collect the repo of the plugin source code.
It would be a great benefit to GitHub, our customers, and PWD if we could create a vibrant community of third-party plugins. Consider refactoring the list of approved plugins into a JSON file or similar file type. Include npm package name, description, and repo. This will allow users of the scanner to find third-party plugins, perform their own security review, file issues on those plugins, contribute fixes, fork/extend, etc.
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.