# Add CodeQL Scanning to a TypeScript Library

Yes. An agent adds a CodeQL code-scanning workflow to your TypeScript library, scoped to the source you ship, with a config file and a weekly run, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-codeql-scanning/typescript-library/). Opens the console with this prompt ready to send, in a Project that has your repository.

## 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`

```json
{
  "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"
    }
  ]
}
```

1. **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.
2. **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.
3. **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.

## 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

- [Add Test Coverage Reporting to CI for a TypeScript Library](https://getrush.ai/run/add-coverage-to-ci/typescript-library/)
- [Run a TypeScript Library's Tests on Bun and Deno in CI](https://getrush.ai/run/add-cross-runtime-tests/typescript-library/)
- [Publish a TypeScript Library to JSR Alongside npm](https://getrush.ai/run/add-jsr-publishing/typescript-library/)

## The same job on other stacks

- [Add CodeQL Scanning to a CMake C++ Project](https://getrush.ai/run/add-codeql-scanning/cmake/)
- [Add CodeQL Scanning to a Cobra CLI](https://getrush.ai/run/add-codeql-scanning/cobra/)
- [Add CodeQL Scanning to a Repository with GitHub Actions](https://getrush.ai/run/add-codeql-scanning/github-actions/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
