Continuous integration (CI) is the backbone of modern software development. It lets you automatically test, build, and validate code every time a teammate pushes a change. For Node.js developers, GitHub Actions offers a free, native solution that integrates directly with your repository. In this guide we’ll walk through every step required to spin up a reliable CI pipeline for a simple Node.js project—no Docker, no external services, just plain GitHub Actions. By the end you’ll have a workflow that runs linting, unit tests, and even deploys to a staging environment, all triggered automatically.
What You’ll Need
- A GitHub account (free tier works fine)
- Basic knowledge of Git and the command line
- Node.js installed locally (v14+ recommended)
- A new or existing Node.js project with a
package.jsonfile - Optional: A test framework like Jest or Mocha
Step 1: Create a GitHub Repository
Start by creating a fresh repository on GitHub. Click the New button, give it a clear name (e.g., my-node-ci-demo), choose Public or Private based on your needs, and initialize it with a .gitignore for Node. Clone the repo to your workstation:
git clone https://github.com/your-username/my-node-ci-demo.git
cd my-node-ci-demoIf you already have a project, simply add the remote and push:
git remote add origin https://github.com/your-username/my-node-ci-demo.git
git push -u origin mainStep 2: Add a Node.js Project
If you started with an empty repo, scaffold a minimal Node.js app:
npm init -y
npm install express
cat > index.js <<'EOF'
const express = require('express');
const app = express();
app.get('/', (req, res) => res.send('Hello, CI!'));
app.listen(3000, () => console.log('Server running on port 3000'));
EOFCommit the starter files:
git add .
git commit -m "Add basic Express app"
git pushStep 3: Write a Simple Test Suite
A CI pipeline is useless without tests. Install Jest (or your preferred framework) and add a basic test:
npm install --save-dev jest
cat > sum.js <<'EOF'
function sum(a, b) { return a + b; }
module.exports = sum;
EOF
cat > sum.test.js <<'EOF'
const sum = require('./sum');
test('adds 1 + 2 to equal 3', () => {
expect(sum(1, 2)).toBe(3);
});
EOF
# Update package.json to use jest
npm set-script test "jest"
git add .
git commit -m "Add Jest test suite"
git pushRun the test locally to confirm it passes:
npm testStep 4: Create the GitHub Actions Workflow File
GitHub Actions looks for YAML files under .github/workflows/. Create a new file called ci.yml:
mkdir -p .github/workflows
cat > .github/workflows/ci.yml <<'EOF'
name: Node.js CI
on:
push:
branches: [ main ]
pull_request:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
node-version: [14.x, 16.x, 18.x]
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Set up Node.js ${{ matrix.node-version }}
uses: actions/setup-node@v3
with:
node-version: ${{ matrix.node-version }}
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Run lint
run: npm run lint --if-present
- name: Run tests
run: npm test
EOFCommit and push the workflow file. GitHub will automatically detect it and start the first run.
Step 5: Configure the Workflow to Install Dependencies and Run Tests
The npm ci command installs exact versions from package-lock.json, guaranteeing reproducible builds. If you have a lint script (e.g., using ESLint), the npm run lint step will catch style issues before the tests execute. Adjust the matrix to match the Node versions you support; the example above tests three LTS releases.
After pushing, navigate to the Actions tab in your repository. You should see a workflow run titled “Node.js CI”. Click it to view logs for each step. A green checkmark means everything passed.
Step 6: Add Environment Variables and Secrets
Many projects need API keys, database URLs, or other secrets during CI. Store them securely in GitHub:
- Go to Settings → Secrets and variables → Actions.
- Click New repository secret.
- Enter a name (e.g.,
DB_URL) and its value, then save.
Reference the secret in your workflow using the ${{ secrets.DB_URL }} syntax. For example, to set an environment variable for a test that needs a database URL:
- name: Run tests with DB
env:
DATABASE_URL: ${{ secrets.DB_URL }}
run: npm test
Remember: never hard‑code secrets in your repo or workflow file; they will be exposed publicly.
Step 7: Enable Branch Protection and Required Checks
To enforce that every pull request passes CI before merging, enable branch protection:
- Navigate to Settings → Branches.
- Click Add rule for the
mainbranch. - Check Require status checks to pass before merging and select “Node.js CI”.
- Optionally enable “Require pull request reviews”.
Now any contributor will see a red “Checks failing” banner until the workflow succeeds, preventing broken code from reaching the main line.
Common Mistakes to Avoid
1. Forgetting to commit package-lock.json – Without it, npm ci can’t guarantee the same dependency tree, leading to flaky builds.
2. Using npm install instead of npm ci – npm ci is faster and more deterministic for CI environments.
3. Hard‑coding secrets – This leaks credentials and violates best practices. Always use GitHub Secrets.
4. Not caching dependencies – Adding cache: 'npm' to setup-node reduces run time dramatically.
5. Running tests that require a UI – Headless browsers need extra setup (e.g., puppeteer with --no-sandbox). If you don’t need them, skip those tests in CI.
Tips and Tricks
• Matrix builds: Test against multiple Node versions or OSes (ubuntu, windows‑latest, macos‑latest) to catch platform‑specific bugs.
• Parallel jobs: Split linting, unit tests, and integration tests into separate jobs to finish faster.
• Artifacts: Use actions/upload-artifact to preserve build outputs (e.g., coverage reports) for later download.
• Cache node_modules: If you prefer npm install, add a manual cache step with actions/cache for the ~/.npm directory.
• Debugging: Add run: echo "::debug::Message" or enable ACTIONS_STEP_DEBUG secret to get verbose logs.
Frequently Asked Questions
Can I use GitHub Actions for private repositories?
Yes. GitHub Actions works with both public and private repos. Private workflows still run on GitHub’s hosted runners, but you must ensure any secrets needed for the job are stored in the repository’s secret store.
How do I debug a failing workflow?
First, examine the log output in the Actions UI—GitHub highlights the exact step that failed. Enable step‑debug logging by adding a secret named ACTIONS_STEP_DEBUG with value true. You can also add temporary run: cat .npm/_logs/* commands to surface npm error logs.
Is there a limit on free minutes?
GitHub provides 2,000 free CI minutes per month for public repositories and for private repos under the free tier you get 2,000 minutes shared across all private repos. If you exceed the quota, builds are queued until the next billing cycle or you upgrade to a paid plan.
Conclusion
Setting up continuous integration with GitHub Actions for a Node.js project is straightforward once you understand the moving parts: a clean repository, a test suite, a workflow YAML file, and proper secret handling. By following the steps above you’ll catch bugs early, enforce code quality, and keep your main branch healthy. As you grow, expand the workflow with deployment jobs, code‑coverage badges, and matrix testing to cover more environments. Happy coding, and enjoy the peace of mind that comes with automated CI!
Photo by Rubaitul Azad on Unsplash
