What you will put in place
- A small JavaScript/TypeScript workflow you can review.
- A first-run checklist with coverage and failure checks.
- A gradual route from observation to enforcement.
1. Choose one repository
Start with a JavaScript or TypeScript repository on GitHub.com, an application owner, and GitHub Actions enabled. Public repositories support code scanning; organization-owned private repositories need GitHub Code Security. Use GitHub’s default setup when a custom workflow is unnecessary.
For this advanced setup, add the workflow through a pull request. If default setup is already enabled, follow GitHub’s switch-to-advanced instructions first. Adjust main to your default branch.
2. Add the workflow
Save this as .github/workflows/codeql.yml. The job checks out the code, initializes JavaScript/TypeScript analysis without a build, and uploads its results. Unlisted token permissions are disabled. No deployment credentials are needed.
name: CodeQL
on:
push:
branches: [main]
pull_request:
branches: [main]
schedule:
- cron: '19 3 * * 1'
permissions: {}
jobs:
analyze:
name: Analyze JavaScript and TypeScript
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: read
security-events: write
actions: read
steps:
- uses: actions/checkout@v4
with:
persist-credentials: false
- uses: github/codeql-action/init@v4
with:
languages: javascript-typescript
build-mode: none
- uses: github/codeql-action/analyze@v4
with:
category: /language:javascript-typescriptGitHub.com example for one interpreted language family. The schedule uses UTC. actions: read supports private-repository code scanning. Major action tags keep the example maintainable; if your policy requires SHA pinning, select reviewed current SHAs and keep them updated. Compiled languages require their own supported build configuration.
3. Check the first successful run
Open Actions and inspect the CodeQL job on the current revision. Then open the repository’s code scanning view. A completed job with zero alerts can be a valid result; an initialization, extraction, or upload failure is a failed check.
- Record the commit, language, workflow version, duration, and tool status.
- Confirm the intended source files are included; document generated or excluded paths.
- Review one existing alert with its application owner, or record that this run reported none.
- Open a harmless change to confirm the pull request check appears on the expected branch. Do not introduce a vulnerability just to test CI.
4. Agree on the merge policy
Run in observation mode until reviewers understand the outputs and integration failures. Decide who owns new findings, who can approve exceptions, and how a timed-out check is handled. Configure required checks separately in your branch rules after that review.
Keep the baseline backlog separate from new pull request findings. A passing check is evidence about this configured analysis on this revision; it is not a complete application audit.
- Success criterion: reliable runs on every in-scope pull request.
- Review criterion: an engineer can identify the affected code and next action.
- Enforcement criterion: the team can resolve findings or record an approved, expiring exception.
References and approach
This guide combines the referenced security guidance with Winfunc’s practical planning recommendations. The examples are starting points to adapt to your application, release process, and risk owners.