# Add CodeQL Scanning to a Repository with GitHub Actions

Yes. An agent adds a CodeQL workflow sized to your repository's languages, runs the analysis once in its sandbox to show what it finds, and opens a PR.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the existing automation before it adds any. In a library like sindresorhus/execa, `.github/` holds exactly one workflow, `main.yml`, a test matrix of Node.js 26, 24 and 22 on ubuntu, macos and windows that runs `npm install`, a lychee link check, `npm run lint` (xo), `npm run type` (`nz` and `tsc --exactOptionalPropertyTypes`) and `npm run unit` (c8 over `node --test`), then uploads coverage. There is a `security.md` with a reporting policy and a `codecov.yml`, but no `codeql.yml`, no `dependabot.yml`, and no `.github/codeql/` directory. `package.json` says `"type": "module"`, ships `index.js` with `index.d.ts` and `types/**/*.ts`, and keeps tests in `test/` and type tests in `test-d/`.

From that it writes `.github/workflows/codeql.yml`: triggers on `push` to the default branch, on `pull_request`, and on a weekly `schedule`; a `permissions` block limited to `security-events: write`, `contents: read` and `actions: read`; one job that checks out the code, runs `github/codeql-action/init@v3` with `languages: javascript-typescript` and `build-mode: none` (JavaScript and TypeScript are analysed from source, so the job never runs `npm install`), then `github/codeql-action/analyze@v3` with a `category` so results from this workflow stay separate if another analysis is added later. The language list is read from the repository, not assumed: a repository with Go or Python directories gets a matrix with one entry per language and the build mode each needs.

A `.github/codeql/codeql-config.yml` keeps the scan honest about scope: `paths-ignore` for `test/fixtures/` and generated files so a deliberately malformed fixture does not turn into an alert, and the query suite the prompt asks for (`security-extended` by default, `security-and-quality` when a maintainer wants style-level findings too). The workflow points at it with `config-file`. If the repository already has GitHub's default setup enabled, the two cannot coexist, so the pull request says to switch default setup off before merging rather than letting the first run fail with that error.

Before opening anything, the agent downloads the CodeQL CLI bundle into the sandbox, runs `codeql database create --language=javascript-typescript` over the checkout and `codeql database analyze` with the same suite the workflow uses, and reads the SARIF it produces. The count of findings by rule, and the files they point at, go into the pull request description, so the first thing a reviewer sees is not an empty promise of security but the actual alerts the Code scanning tab will show after merge.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add CodeQL code scanning to this repository. Read the existing workflows under .github/workflows first and detect the languages in the tree. Write a codeql.yml workflow that runs on push to the default branch, on pull requests and on a weekly schedule, with least-privilege permissions, one analysis per language using github/codeql-action/init and analyze v3, build-mode none for interpreted languages, and a category per analysis. Add a .github/codeql/codeql-config.yml that ignores test fixtures and generated files and selects the security-extended suite. Run the CodeQL CLI in the sandbox against the checkout with the same suite, summarise the findings by rule in the pull request description, and note that GitHub's default setup must be disabled before the workflow can upload results. Do not change the existing CI workflow.",
  "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

What comes back is a pull request adding `.github/workflows/codeql.yml` and `.github/codeql/codeql-config.yml`, with no change to the existing CI workflow. The description lists the languages detected, the query suite chosen, the ignored paths, and a table of what the sandbox analysis found, rule by rule with file paths, so a maintainer can judge the signal before the Code scanning tab exists.

The run's record keeps the CLI's `database create` and `analyze` output, including the SARIF summary, so a reviewer can see that the analysis completed on the whole tree and how long it took, which is a fair preview of what the scheduled job will cost in Actions minutes.

Before merging, a reviewer disables default setup under the repository's code security settings if it is on, decides whether the `CodeQL` check should be required by branch protection, and triages the findings the description previews, since merging the workflow is what turns them into open alerts.

## Run it on every new repository in the org

A handler on your server that receives GitHub's `repository` webhook for the `created` action sends one `POST /o/{org}/sessions` with this body and the new repository in `resources`, with a `request_id` that is a UUID v5 of the repository's id so a redelivered webhook returns the run already started. Each new repository then gets a CodeQL pull request within minutes of existing, sized to whatever languages its first commit contains.

Set a webhook URL on the API key and Rush posts `run.completed` with the `session_url` when the pull request is up, so the handler can record which repositories still have the pull request open and nudge their owners.

## Why run it on Rush?

The reason CodeQL workflows sit unmerged for months is that nobody knows what they will find until they run, and nobody wants to merge a workflow that opens forty alerts on day one. Running the analysis in a sandbox first, with the exact suite and ignore list the workflow will use, turns that unknown into a table in the pull request. The agent can do that because its sandbox is a real computer that can download the CLI bundle, build the database and read the SARIF, with every command kept in the run's record.

It also scales across an organisation: one request per repository, each in its own sandbox, each pull request specific to that repository's languages and fixtures, instead of a single template workflow copied everywhere and failing on the repositories whose build mode or paths differ.

## Frequently asked questions

### Does CodeQL need to build a JavaScript or TypeScript project?

No. With `build-mode: none` the analysis reads the source directly, which is why the workflow for a library like execa never runs `npm install`. Compiled languages such as Go, Java or C++ do need a build, and for those the agent either lets `autobuild` run or writes the build step the repository's CI already uses.

### Will the workflow conflict with GitHub's default setup?

Yes, if default setup is enabled: an advanced-setup workflow cannot upload results while default setup is on, and the first run fails saying so. The pull request names the setting to switch off before merging. Running the analysis in the sandbox first does not touch that setting.

### How much CI time does it add?

The pull request does not guess. The sandbox run's record shows how long the database build and analysis took on this repository, and the scheduled weekly run is the same work. Pull request runs can be limited with `paths-ignore` in the trigger so documentation-only changes skip the scan.

### Is the security-extended suite too noisy?

It is the default for most repositories because it adds lower-confidence security queries without the style rules of `security-and-quality`. The preview in the pull request shows what it produces on your code; if the extended queries only add noise, the config file switches to the default suite with a one-line change.

### Does this work on private repositories?

The workflow is the same. Code scanning on a private repository requires GitHub Advanced Security on the organisation's plan, while public repositories get it at no cost. The sandbox analysis runs either way, so the preview of findings is available even where the upload will need a licence.

## More GitHub Actions jobs

- [Cancel Superseded Runs with Concurrency Groups and Job Timeouts in GitHub Actions](https://getrush.ai/run/add-concurrency-groups/github-actions/)
- [Add Coverage Reporting to a GitHub Action's CI](https://getrush.ai/run/add-coverage-to-ci/github-actions/)
- [Set Up Dependabot Auto-merge with GitHub Actions](https://getrush.ai/run/add-dependabot-auto-merge/github-actions/)

## The same job on other stacks

- [Add CodeQL Scanning to a Go CLI](https://getrush.ai/run/add-codeql-scanning/go-cli/)
- [Add CodeQL Scanning to a Gradle Project](https://getrush.ai/run/add-codeql-scanning/gradle/)
- [Add CodeQL Scanning to a Maven Spring Boot Project](https://getrush.ai/run/add-codeql-scanning/maven/)

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