To make GitHub run your Node.js tests on every pull request, add a workflow file at .github/workflows/node-tests.yml that triggers on pull_request, checks out the code, installs the Node version your project uses, installs dependencies, and runs your existing test script. Commit that file to the repository’s default branch. Every new pull request—and every later push to it—will then show a workflow run in GitHub’s Checks area. Start by confirming npm test already works on your computer; automation should repeat a known-good command, not invent one.
Check the project before writing a workflow
Open package.json and look at the scripts section. A basic project often has something like "test": "vitest run", "test": "jest", or a framework-specific test command. Run the same command locally with npm test. Fix any local failure first, because GitHub Actions will faithfully report that failure without explaining your application better than the test runner does.
Also notice the lockfile. This guide uses npm ci because it installs the exact dependency versions in package-lock.json and fails if the lockfile and package.json disagree. If your repository uses yarn.lock or pnpm-lock.yaml, use that package manager’s documented immutable install command instead. Mixing package managers in CI can produce confusing differences from a developer’s machine.
Finally, check the Node version expected by the project. It may be listed in an engines field, an .nvmrc file, project documentation, or your hosting configuration. Choose a maintained version that the project supports; do not guess from the newest version listed on a download page. GitHub’s official Building and testing Node.js guide is the current reference when the setup screens or action versions change.
Add a small pull-request workflow
Create the directories and file .github/workflows/node-tests.yml. GitHub treats YAML files in that folder as workflows. This is a deliberately small example for an npm project with a package-lock.json and an npm test script:
name: Node.js tests
on:
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: npm test
The pull_request trigger is the part that connects this job to review work. It runs when a pull request is opened, reopened, synchronized with new commits, or otherwise updated by the events GitHub supports. actions/checkout puts the pull request’s code on the temporary runner. actions/setup-node supplies Node.js, and the two run lines use commands you can run yourself.
Replace 22 only if your project expects another Node release. If tests require a build first, add the project’s real build command before npm test. If they need a service, database, browser, or environment variable, do not quietly delete that requirement to get a green check. Read the test tool’s documentation and add the minimal supported CI setup.
Open a pull request and read the first result
Commit the workflow, push a branch, and open a pull request. GitHub should list Node.js tests under the pull request’s Checks tab or in the conversation timeline. You can also open the repository’s Actions tab, select the workflow run, and expand the failed step to read its log.
The first failure is usually ordinary setup friction: an unsupported Node version, a missing lockfile, a test script that does not exist, or a command that relies on a local service. Work from the first useful error in the log, make one small correction, and push it to the same branch. The pull request run will update automatically. Avoid responding to a red check by adding continue-on-error: true; that makes the workflow look successful while hiding the problem reviewers needed it to reveal.
A green workflow means the configured command passed in that clean environment. It does not prove the application has no bugs, that every deployment works, or that the test suite covers every important behavior. Treat it as one useful signal in review, alongside readable changes, test quality, and human judgment.
Match the workflow to the repository, not a generic snippet
The example is a starting point, not a universal template. A monorepo may need working-directory for each package. A project with multiple supported Node versions may use a matrix. A test command that depends on secrets needs a deliberate design: pull requests from forks have tighter token and secret restrictions, so never work around that by exposing credentials in the workflow file or logs.
You can use the Actions tab’s Node.js starter workflow as a guided alternative, then compare its commands with your repository. GitHub maintains the actions used above in the official repositories for checkout and setting up Node. Pinning to the documented major versions shown there keeps a basic workflow understandable while you follow upstream release and security guidance.
Once the test check is reliable, decide whether your repository should require it before merging. Branch protection and rulesets are team decisions: a required check can prevent an accidental merge after a failed test, but it can also block work if the workflow is flaky. Start by making the test stable and quick, then agree with the team on the merge rule.
Add security and review habits around the check
Automated tests and security scanning solve different problems. Tests tell you whether the behavior you specified still works; code scanning looks for certain risky code patterns. If you want a separate, practical next step, see our guide to turning on GitHub code scanning for an existing repository. Keep its findings and failed tests visible rather than treating either dashboard as a score to game.
It is also worth making the workflow easy for a future maintainer to understand. Give it a plain name, use the project’s existing commands, and leave a short note in the README or contributing guide if a local prerequisite is non-obvious. If you use an AI assistant to draft a command or explain an error, verify it against the actual scripts and logs before committing it. The same “review before acting” habit makes everyday AI planning more useful; our ChatGPT Voice action-plan guide offers a simple example.
Workflow minutes, available runners, and some features can vary with a repository’s visibility and your GitHub plan. Check GitHub’s current documentation if you are estimating cost or need a particular runner. For most small Node.js projects, though, this small workflow provides a valuable baseline: every pull request gets the same repeatable test command before someone decides to merge it.
Official sources
- GitHub Docs: Building and testing Node.js
- GitHub Docs: Workflow syntax for GitHub Actions
- GitHub: actions/setup-node repository