What the agent does
The agent reads how the library is built and tested, because a scanning workflow must fit beside it. In a package laid out like sindresorhus/ky, package.json is "type": "module" with engines.node >=22, exports pointing at ./distribution/index.js and its types, and a test script of xo && npm run build && tsc --project tsconfig.test.json && ava; build is del-cli distribution && tsc --project tsconfig.dist.json, and distribution/ is not committed. The source is TypeScript under source/ (core/, errors/, types/, utils/, index.ts), the tests are 45 files under test/ plus type tests in test-d/, and the only workflow, .github/workflows/main.yml, runs npx ava on macos-latest for Node latest, 24 and 22 and a second job that installs Playwright browsers. .github/security.md says where to report a vulnerability. There is no CodeQL, Dependabot or other scanning configuration.
The workflow the agent adds, .github/workflows/codeql.yml, uses github/codeql-action/init and github/codeql-action/analyze at the action's current major, v4, with languages: javascript-typescript, the one identifier that covers both languages; javascript alone would still analyze the TypeScript, but the combined name is what the docs ask for. JavaScript and TypeScript need no build for CodeQL, so there is no autobuild step and no npm install, which also keeps the library's dependencies out of the database. It runs on ubuntu-latest, not the macOS runners the tests use, because the analysis is the same on any platform and macOS minutes cost more. Permissions are the minimum the upload needs: security-events: write to post results, contents: read to check out, and actions: read for the workflow run. Triggers are push to the default branch, pull_request against it, and a weekly schedule, so new queries in the CodeQL bundle run against unchanged code.
A config file, .github/codeql/codeql-config.yml, named by the config-file input, sets paths to source and paths-ignore to test, test-d and distribution, so a finding always points at a line the package ships and a test helper that builds odd URLs on purpose does not show up as an alert. It selects the security-extended suite: the default suite's queries plus lower-precision ones, which on a 40-file HTTP client is a short list to read, while security-and-quality would add maintainability findings xo already covers. The agent lists the queries in the pull request so the choice is visible.
The workflow cannot run in the sandbox, because CodeQL's upload needs the repository's GitHub token, so the agent checks what it can: it runs actionlint on the new file, confirms every action reference pins a major that exists, and runs the CodeQL CLI locally with codeql database create --language=javascript-typescript on source/ and codeql database analyze with the same suite, so the pull request can quote how many results the queries produce on the current code. It adds a results badge line to the README only if the README already has a CI badge, and leaves security.md as it is, noting in the pull request that scanning alerts and the advisory form are different channels.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add CodeQL code scanning to this TypeScript library. Read package.json (the scripts, exports and engines), tsconfig.json, tsconfig.dist.json, tsconfig.test.json, .github/workflows/main.yml, .github/security.md and the layout of source, test and test-d first. Add .github/workflows/codeql.yml using github/codeql-action/init and analyze at their current major with languages set to javascript-typescript, no build step, running on ubuntu-latest, with security-events write, contents read and actions read permissions, on push to the default branch, pull requests and a weekly schedule. Add .github/codeql/codeql-config.yml referenced by config-file that limits paths to the shipped source, ignores the test directories and the build output, and selects the security-extended suite. Run actionlint on the workflow, then run the CodeQL CLI in the sandbox to create a database for the source and analyze it with the same suite, and quote the result count. Do not add other scanners. Open a pull request that lists the queries the suite adds and explains each choice.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request adds .github/workflows/codeql.yml and .github/codeql/codeql-config.yml and touches nothing else, unless the README already carries a CI badge, in which case it gains a code-scanning badge beside it. Its description quotes the actionlint result, the CodeQL CLI's database creation and analysis output with the number of results per query on the current source, and a table of the suite's queries with one line on each.
A reviewer checks the paths: source in, test, test-d and distribution out, so an alert can only point at shipped code. They check the schedule's day and hour, the permissions block, and whether security-extended is the level of noise they want, which is one line in the config file to change. Once merged, the first run on the default branch populates the repository's Security tab, and alerts on later pull requests appear as checks.
The existing main.yml, the test matrix and the publish process are untouched, and the new workflow adds no dependency to the package.
Run it on every new repository in the organisation
A handler on your own server, listening for your organisation's repository-created webhook, sends this body to POST /o/{org}/sessions with the new repository in resources and a request_id that is a UUID v5 of the repository's id, so a redelivered webhook returns the run already started. Each run opens one pull request with the scanning workflow fitted to that repository's layout, and the key's webhook_url receives run.completed.
On repositories that already scan, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize can run read-only with a prompt that checks a change under .github/workflows/ keeps the CodeQL job's permissions and language, and comments when it does not. The trigger adds the event after the prompt; it fills in no placeholder.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
A scanning workflow is small, but getting it wrong is silent: the wrong language identifier analyzes nothing, a missing security-events permission fails the upload, a path filter that includes the tests buries the real alerts. The agent reads the repository's layout and the CodeQL action's documentation for the current major, and runs the CodeQL CLI against the source in its sandbox so the pull request says what the queries find today rather than guessing.
Doing this for every library in an organisation is the same reading repeated with different paths, and a run per repository produces one fitted pull request each, with the commands and their output kept in each run's record.
Frequently asked questions
Why javascript-typescript and not typescript?
CodeQL analyzes JavaScript and TypeScript with one extractor, and javascript-typescript is the identifier its documentation gives for either or both. The older names javascript and typescript still work and do not exclude the other language, so the combined name is used to say what is meant.
Does it need a build step?
No. CodeQL reads JavaScript and TypeScript source directly, so the workflow has no autobuild and runs no npm install. That also keeps third-party code out of the database, which is why distribution/ and node_modules never appear in results.
Will it fail pull requests?
The workflow itself passes when the analysis uploads. Whether a new alert blocks merging is a branch-protection setting on the repository; the pull request explains how to require the check and leaves that decision to the maintainer.
Why exclude the tests?
Test files build malformed URLs, fake servers and odd headers on purpose, and the queries flag exactly that. Excluding test and test-d keeps every alert on a line the package ships, and the config file is where to widen it if you want tests scanned too.
Why not security-and-quality?
That suite adds maintainability and reliability queries whose findings overlap with what xo enforces on every npm test. security-extended keeps the scan about security, and the suite name is one line in the config file if you want the larger set.
More TypeScript library jobs
The same job on other stacks
- Add CodeQL Scanning to a CMake C++ Project (CMake)
- Add CodeQL Scanning to a Cobra CLI (Cobra)
- Add CodeQL Scanning to a Repository with GitHub Actions (GitHub Actions)