How to Run a CI/CD Pipeline That Tests Against a Live Local Environment

The Integration Testing Problem

Unit tests are easy to run in CI because they have no external dependencies. They test a function, mock everything else, and the runner does not need to know anything about the real world. You push, the pipeline runs, you get a green or red result.

Integration tests are different. They verify that different parts of your system work together correctly. Your API and its database, your app and a third-party payment provider, your webhook handler and the service that sends the webhooks. Each of these requires a real running service to test against, not a mock.

Three scenarios come up repeatedly in real projects:

Two Complementary Approaches

There is no single answer that covers every scenario. Two approaches work well and are often used together in the same project.

Approach A: Service Containers in GitHub Actions

GitHub Actions supports service containers, Docker containers that run alongside your workflow job and are accessible to it on localhost. This is the cleanest way to run database integration tests in CI without any external setup.

Node.js API with PostgreSQL integration tests

# .github/workflows/integration-tests.yml
name: Integration Tests

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

jobs:
  integration:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Run database migrations
        env:
          DATABASE_URL: postgresql://testuser:testpassword@localhost:5432/testdb
        run: npm run migrate

      - name: Run integration tests
        env:
          DATABASE_URL: postgresql://testuser:testpassword@localhost:5432/testdb
          NODE_ENV: test
        run: npm run test:integration

The postgres service container starts before your test steps. The --health-cmd pg_isready option makes GitHub Actions wait until the database is fully ready before running your tests. Your test code connects to localhost:5432 exactly as it would locally.

Python with PostgreSQL and Redis

jobs:
  integration:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:
        image: redis:7-alpine
        ports:
          - 6379:6379
        options: >-
          --health-cmd "redis-cli ping"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Run integration tests
        env:
          DATABASE_URL: postgresql://testuser:testpassword@localhost:5432/testdb
          REDIS_URL: redis://localhost:6379
        run: pytest tests/integration/ -v

Approach B: Expose a Local Environment with Localtonet

Service containers solve the database problem but they cannot help when a third-party service needs to call your code. Stripe cannot deliver a webhook to a GitHub Actions runner. Google cannot redirect an OAuth callback to a Docker container inside CI. For these scenarios, you need your local environment to be reachable from the internet.

The setup is straightforward. Run your application locally, create a Localtonet HTTP tunnel, and configure the third-party service to use the tunnel URL. Your local server receives the real traffic and your test suite asserts the outcome.

Webhook Integration Testing in Practice

Webhook testing is the most common reason developers need a public URL during local development. Here is a concrete example using Stripe, but the same pattern applies to GitHub webhooks, Twilio, Shopify, or any other service that delivers events via HTTP.

Testing a Stripe payment webhook locally

// webhook.js (Express example)
const express = require('express');
const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);
const app = express();

app.post('/webhooks/stripe',
    express.raw({ type: 'application/json' }),
    (req, res) => {
        const sig = req.headers['stripe-signature'];
        let event;

        try {
            event = stripe.webhooks.constructEvent(
                req.body,
                sig,
                process.env.STRIPE_WEBHOOK_SECRET
            );
        } catch (err) {
            return res.status(400).send(`Webhook Error: ${err.message}`);
        }

        if (event.type === 'payment_intent.succeeded') {
            const paymentIntent = event.data.object;
            console.log('Payment succeeded:', paymentIntent.id);
            // Update your database, send confirmation email, etc.
        }

        res.json({ received: true });
    }
);

app.listen(3000, () => console.log('Server running on port 3000'));

Testing a GitHub webhook locally

# webhook_handler.py (Flask example)
from flask import Flask, request, abort
import hmac
import hashlib
import os

app = Flask(__name__)

@app.route('/webhooks/github', methods=['POST'])
def github_webhook():
    signature = request.headers.get('X-Hub-Signature-256', '')
    secret = os.environ['GITHUB_WEBHOOK_SECRET'].encode()
    body = request.get_data()

    expected = 'sha256=' + hmac.new(secret, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(signature, expected):
        abort(401)

    event = request.headers.get('X-GitHub-Event')
    payload = request.json

    if event == 'push':
        branch = payload['ref'].split('/')[-1]
        commit = payload['head_commit']['message']
        print(f'Push to {branch}: {commit}')
        # Trigger your CI logic, notify team, etc.

    return '', 200

if __name__ == '__main__':
    app.run(port=5000)

Create the Localtonet tunnel for port 5000, go to your GitHub repository under Settings → Webhooks → Add webhook, and enter your tunnel URL as the Payload URL. Every push to the repository delivers a real webhook to your local handler.

When to Use Each Approach

Frequently Asked Questions