Overview

GitHub Actions provides built-in CI/CD capabilities for automating your testing workflow. This guide walks you through setting up automatic test execution on every push and pull request.

Prerequisites

  • GitHub repository
  • Existing test suite (npm test, pytest, etc.)
  • Basic familiarity with YAML

Step 1: Create Workflow Directory

In your repository root, create the workflows directory:

1

mkdir -p .github/workflows

This is where GitHub Actions looks for workflow definitions.

Step 2: Create Workflow File

Create .github/workflows/test.yml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

name: Run Tests

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      matrix:
        node-version: [18.x, 20.x]
    
    steps:
    - name: Checkout code
      uses: actions/checkout@v4
    
    - name: Setup Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v4
      with:
        node-version: ${{ matrix.node-version }}
        cache: 'npm'
    
    - name: Install dependencies
      run: npm ci
    
    - name: Run tests
      run: npm test
    
    - name: Upload coverage reports
      uses: codecov/codecov-action@v3
      if: matrix.node-version == '20.x'
      with:
        file: ./coverage/coverage-final.json

Step 3: Customize for Your Tech Stack

For Python Projects

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

- name: Set up Python
  uses: actions/setup-python@v5
  with:
    python-version: '3.11'

- name: Install dependencies
  run: |
    python -m pip install --upgrade pip
    pip install -r requirements.txt

- name: Run tests
  run: pytest

For Go Projects

1
2
3
4
5
6
7

- name: Set up Go
  uses: actions/setup-go@v5
  with:
    go-version: '1.21'

- name: Run tests
  run: go test -v ./...

Step 4: Add Status Badge to README

Add this markdown to your README.md:

1

![Tests](https://github.com/USERNAME/REPO/workflows/Run%20Tests/badge.svg)

Replace USERNAME and REPO with your values.

Step 5: Commit and Push

1
2
3

git add .github/workflows/test.yml
git commit -m "Add GitHub Actions testing workflow"
git push origin main

Step 6: Verify Execution

  1. Navigate to your repository on GitHub
  2. Click the Actions tab
  3. You should see your workflow running
  4. Click on the workflow run to see details

Advanced Configuration

Run on Schedule

Add to the on: section:

1
2

schedule:
  - cron: '0 2 * * *'  # Run at 2 AM daily

Cache Dependencies

Already included in the example above with:

1

cache: 'npm'

This speeds up workflow runs significantly.

Parallel Jobs

Test multiple configurations simultaneously using matrix strategy (shown in example).

Troubleshooting

Tests pass locally but fail in Actions

Common causes:

  • Environment variables not set
  • Different Node.js/Python versions
  • OS-specific dependencies

Solution: Add debugging steps:

1
2
3
4
5

- name: Debug environment
  run: |
    node --version
    npm --version
    echo $PATH

Workflow doesn’t trigger

Check:

  • Workflow file is in .github/workflows/
  • YAML syntax is valid (use a validator)
  • Branch names match your on: configuration

Best Practices

  1. Use npm ci instead of npm install for faster, more reliable installs
  2. Cache dependencies to reduce build time
  3. Set up branch protection requiring tests to pass before merge
  4. Upload artifacts for test reports and coverage
  5. Use secrets for API keys and credentials

Next Steps

  • Add code coverage reporting (Codecov, Coveralls)
  • Set up deployment workflows
  • Add linting and formatting checks
  • Implement matrix testing across OS platforms

Resources