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

Two architectures with different trust boundaries

The phrase “test against a live local environment” can describe two fundamentally different systems. In the first, the database, cache, application, and tests all run within a GitHub Actions job. In the second, the application remains on a developer-controlled machine and receives requests from a CI runner or an external provider through a public tunnel.

Keep these models separate when designing the pipeline. A self-contained runner is usually the best default for pull requests because it is repeatable and does not depend on a workstation. A tunnel is appropriate when the test specifically requires an internet-originated request, a provider callback, a device outside the local network, or behavior that only exists in a developer-managed environment.

What a hosted runner can and cannot receive

A third-party service normally cannot initiate a connection to an unexposed GitHub-hosted runner. The runner makes outbound connections, while its application ports are not automatically published as stable internet endpoints. It is technically possible to add a separate inbound exposure mechanism, but that is a different architecture and requires a verified installation, authentication, URL-discovery, lifecycle, and security workflow.

This guide does not claim that the Localtonet client can be installed or automated inside GitHub Actions because no verified Localtonet command sequence or URL-discovery workflow has been supplied for that use case. Instead, the tunnel architecture keeps the Localtonet client on the developer-controlled device and passes the assigned public URL into a deliberately triggered CI job.

Prerequisites and repository responsibilities

A pipeline file cannot make an application testable by itself. Before adding either workflow, define the commands, health endpoints, credentials, and expected results that belong to the repository. The examples below use conventional names, but your repository must actually implement them.

Requirements for the self-contained GitHub Actions job

• A GitHub repository with Actions enabled.
• A Linux runner with Docker available. GitHub Actions service containers require a Linux runner and Docker.
• A lockfile compatible with npm ci, such as package-lock.json.
• An npm run migrate script that applies the test schema.
• An npm run start:test script that starts the application without detaching itself unexpectedly.
• An npm run test:integration script that exits nonzero when assertions fail.
• An application readiness endpoint, represented below as /health/ready.
• Deterministic fixture or seed logic that never imports production records.
• A test reporter configured to write machine-readable results if you want to upload them as artifacts.

Container image tags should identify a deliberate version. A broad tag can change underneath the pipeline. For stronger supply-chain reproducibility, use the image digest approved by your project. GitHub Actions references can also be pinned to reviewed commit SHAs when your security policy requires immutable dependencies.

Requirements for a tunneled environment

• A dedicated local test application and database, not a production application copied onto a workstation.
• The Localtonet client installed and running on the device that can reach the application.
• A device-specific AuthToken selected without exposing it in logs, screenshots, workflow inputs, or source control.
• A current Localtonet relay server selected from the options available in the product.
• A verified local IP address and port for the HTTP application.
• A protected readiness route and test API, or a provider-signed webhook route.
• A test account or sandbox account for the external provider.
• An operator responsible for starting the environment, monitoring it, and stopping or deleting the tunnel afterward.

Architecture A: build a complete integration-test job

The following Node.js workflow creates an isolated PostgreSQL service, installs locked dependencies, applies migrations, starts the application, waits for application-level readiness, runs integration tests, collects artifacts, and terminates the application during cleanup. It also prevents overlapping runs for the same workflow and branch or pull request.

name: Integration Tests

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

permissions:
  contents: read

concurrency:
  group: integration-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  integration:
    runs-on: ubuntu-latest
    timeout-minutes: 20

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

    env:
      NODE_ENV: test
      DATABASE_URL: postgresql://testuser:testpassword@localhost:5432/testdb
      TEST_BASE_URL: http://127.0.0.1:3000

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

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

      - name: Install locked dependencies
        run: npm ci

      - name: Apply test database migrations
        run: npm run migrate

      - name: Start test application
        shell: bash
        run: |
          npm run start:test > application.log 2>&1 &
          echo $! > application.pid

      - name: Wait for application readiness
        shell: bash
        run: |
          for attempt in {1..60}; do
            if curl --silent --show-error --fail \
              --max-time 2 \
              "$TEST_BASE_URL/health/ready"; then
              exit 0
            fi
            sleep 2
          done

          echo "Application did not become ready within 120 seconds."
          cat application.log || true
          exit 1

      - name: Run integration assertions
        run: npm run test:integration

      - name: Upload logs and test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: integration-results
          path: |
            application.log
            test-results/
          if-no-files-found: warn
          retention-days: 7

      - name: Stop test application
        if: always()
        shell: bash
        run: |
          if [ -f application.pid ]; then
            kill "$(cat application.pid)" 2>/dev/null || true
          fi

Why both container health and application readiness matter

The PostgreSQL health command reports the health status of the database container. It reduces startup races, but it does not prove that your application has connected successfully, that migrations completed, or that the API can serve a real request. The separate readiness loop tests the application after migrations and startup.

A readiness route should check only the dependencies required for the test and return promptly. Do not place secrets, database contents, stack traces, or administrative controls in its response. If the route is included in production builds, restrict the information it reveals.

Credentials and fixtures

The PostgreSQL credentials in this example exist only inside the disposable CI job. They are not suitable for a shared or production database. If a test requires a third-party sandbox credential, store it as a GitHub Actions secret and expose it only to the step that needs it. Be especially careful with workflows triggered from forks because repository secrets are intentionally restricted in many forked pull-request contexts.

Run migrations before seeding fixtures, give each test an independent record namespace, and clean state between tests. Common application-level strategies include transaction rollback, a schema per suite, or a database per worker. The service container gives isolation between jobs, but tests within one job can still conflict when they share records or run concurrently.

Python variation with PostgreSQL and Redis

The same architecture works for Python when the repository defines its dependency and test commands. The following service configuration is valid for a Linux job whose steps run directly on the runner. The tests connect through mapped localhost ports.

jobs:
  python-integration:
    runs-on: ubuntu-latest
    timeout-minutes: 20

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

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

    env:
      DATABASE_URL: postgresql://testuser:testpassword@localhost:5432/testdb
      REDIS_URL: redis://localhost:6379

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: pip

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

      - name: Apply migrations
        run: python manage.py migrate

      - name: Run integration tests
        run: pytest tests/integration/ -v --junitxml=test-results/pytest.xml

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: python-integration-results
          path: test-results/
          if-no-files-found: warn
          retention-days: 7

Replace python manage.py migrate with the migration command implemented by your project. If these tests also need a running HTTP process, start it, perform a bounded application-readiness check, capture its logs, and stop it using the same lifecycle shown in the Node.js job.

Architecture B: expose the local test application with Localtonet

With Localtonet, the client application on your device establishes an outbound connection to our relay. The HTTP tunnel then supplies a public HTTPS address that forwards to the configured local IP address and port. No inbound router port forwarding, public IP address, VPN setup, or inbound firewall change is required for this tunnel workflow.

The public endpoint exists only while the selected client or device is connected and the tunnel is running. Creating a tunnel does not start it. The operator must select Start, verify the assigned URL, and later stop or delete the tunnel.

Run a controlled CI job against the temporary URL

The evidence available for this guide does not establish a documented Localtonet mechanism for automatically discovering a newly assigned tunnel URL inside GitHub Actions. It also does not establish a verified workflow for installing the Localtonet client in a hosted runner. We therefore should not pretend that URL handoff and tunnel creation are automatic.

A safe, supportable pattern is to start and verify the tunnel on the developer-controlled device, then invoke a restricted workflow_dispatch job with the public base URL. The job receives the URL explicitly, waits for the local application to become ready, authenticates to a dedicated test API, runs assertions, uploads results, and times out if the workstation disappears.

name: Controlled Local Environment Test

on:
  workflow_dispatch:
    inputs:
      public_base_url:
        description: Verified temporary HTTPS base URL
        required: true
        type: string

permissions:
  contents: read

concurrency:
  group: controlled-local-integration
  cancel-in-progress: false

jobs:
  test-local-environment:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: local-integration

    env:
      TEST_BASE_URL: ${{ inputs.public_base_url }}
      TEST_API_TOKEN: ${{ secrets.LOCAL_TEST_API_TOKEN }}

    steps:
      - name: Validate input scheme
        shell: bash
        run: |
          case "$TEST_BASE_URL" in
            https://*) ;;
            *)
              echo "The test URL must use HTTPS."
              exit 1
              ;;
          esac

      - name: Check out repository
        uses: actions/checkout@v4

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

      - name: Install locked dependencies
        run: npm ci

      - name: Wait for remote application readiness
        shell: bash
        run: |
          for attempt in {1..30}; do
            if curl --silent --show-error --fail \
              --max-time 5 \
              --header "Authorization: Bearer $TEST_API_TOKEN" \
              "$TEST_BASE_URL/test/ready" \
              > readiness-response.txt; then
              exit 0
            fi
            sleep 5
          done

          echo "The local environment did not become ready within 150 seconds."
          exit 1

      - name: Run remote integration assertions
        env:
          BASE_URL: ${{ inputs.public_base_url }}
          API_TOKEN: ${{ secrets.LOCAL_TEST_API_TOKEN }}
        run: npm run test:remote-integration

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: controlled-local-test-results
          path: |
            readiness-response.txt
            test-results/
          if-no-files-found: warn
          retention-days: 7

This workflow assumes the repository implements test:remote-integration and writes reports to test-results/. Tests should use BASE_URL as their origin and send API_TOKEN only to the dedicated test application. Never print the token or include it in the URL.

Configure the local-integration GitHub environment with appropriate reviewers if manual approval is required. Restrict who can dispatch the workflow because an arbitrary URL supplied to a privileged runner can create a server-side request forgery risk. If your organization needs unattended tunnel creation, URL discovery, or teardown, implement it only from current documented Localtonet API behavior and have that automation reviewed separately.

Design assertions around observable outcomes

A remote test should do more than receive HTTP 200. Create a unique run identifier, submit a test request, poll a protected status route for a bounded period, and verify the expected state transition. Make retries safe by using an idempotency key or the unique run identifier. Capture response status, sanitized response bodies, correlation IDs, and application logs without recording credentials or personal data.

Test webhook delivery without weakening verification

A webhook tunnel changes how the provider reaches your application, but it should not change the provider’s security model. Use the provider’s test or sandbox mode, store the endpoint signing secret outside source control, preserve the exact request body required by the signature algorithm, compare signatures safely, reject stale or invalid messages when the provider’s protocol supports timestamp validation, and make event processing idempotent.

Provider dashboard labels and test-event controls can change. Use the provider’s current first-party documentation and interface to create the endpoint, choose event types, obtain or rotate the signing secret, send a test delivery, and inspect delivery attempts. Do not rely on an old menu path copied from a tutorial.

Stripe webhook handler using the raw request body

const express = require('express');
const Stripe = require('stripe');

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

// Register this route before any JSON body parser that would modify the body.
app.post(
  '/webhooks/stripe',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    const signature = req.headers['stripe-signature'];

    let event;
    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        signature,
        process.env.STRIPE_WEBHOOK_SECRET
      );
    } catch (error) {
      return res.status(400).send('Invalid webhook signature');
    }

    try {
      // hasProcessedEvent and recordProcessedEvent must use durable,
      // atomic storage keyed by the provider event ID.
      if (await hasProcessedEvent(event.id)) {
        return res.status(200).json({ received: true, duplicate: true });
      }

      if (event.type === 'payment_intent.succeeded') {
        const paymentIntent = event.data.object;
        await processTestPayment(paymentIntent);
      }

      await recordProcessedEvent(event.id);
      return res.status(200).json({ received: true });
    } catch (error) {
      console.error('Webhook processing failed', {
        eventId: event.id,
        eventType: event.type
      });
      return res.sendStatus(500);
    }
  }
);

The signing secret belongs in the local environment’s secret store, not in code or a pipeline input. Use the signing secret associated with the exact test endpoint. Rotate it if it is exposed. Stripe can retry deliveries, and delivery can occur more than once, so the event ID must be recorded atomically before a duplicate can repeat a state-changing operation.

Webhook endpoints should respond within the provider’s required time window. For production designs, lengthy processing is commonly handed to a durable queue after signature verification and idempotent acceptance. For a local test, keep processing bounded and inspect the provider’s delivery log alongside local application logs.

GitHub webhook handler with safe payload access

from flask import Flask, request, abort
import hashlib
import hmac
import json
import os

app = Flask(__name__)

@app.post('/webhooks/github')
def github_webhook():
    body = request.get_data(cache=True)
    supplied_signature = request.headers.get('X-Hub-Signature-256', '')
    delivery_id = request.headers.get('X-GitHub-Delivery', '')
    event_name = request.headers.get('X-GitHub-Event', '')

    secret = os.environ['GITHUB_WEBHOOK_SECRET'].encode('utf-8')
    digest = hmac.new(secret, body, hashlib.sha256).hexdigest()
    expected_signature = f'sha256={digest}'

    if not hmac.compare_digest(supplied_signature, expected_signature):
        abort(401)

    if not delivery_id:
        abort(400)

    if delivery_already_processed(delivery_id):
        return '', 200

    payload = json.loads(body.decode('utf-8'))

    if event_name == 'push':
        ref = payload.get('ref')
        head_commit = payload.get('head_commit')
        commit_message = (
            head_commit.get('message')
            if isinstance(head_commit, dict)
            else None
        )

        process_test_push(
            delivery_id=delivery_id,
            ref=ref,
            commit_message=commit_message
        )

    record_processed_delivery(delivery_id)
    return '', 200

The example reads the exact request bytes before parsing JSON, verifies X-Hub-Signature-256, uses a constant-time comparison, and does not assume that head_commit is always present. Implement delivery_already_processed and record_processed_delivery with durable, atomic storage. GitHub can redeliver events, so processing must tolerate duplicates.

Create the webhook in a test repository or another deliberately limited context. Configure only the events required by the test, use a unique random secret, and enter the current Localtonet public URL plus the handler path as the payload URL. After triggering a test event, compare the provider delivery ID, HTTP status, request timestamp, local log correlation ID, and resulting test record.

Verify locally, publicly, and end to end

Test each network segment independently. This avoids blaming the tunnel when the application is not listening, or blaming the application when the provider is still configured with an old URL.

Security and operational controls

A public tunnel shifts an application from loopback-only access to internet-reachable access for the duration of the tunnel. Treat that as a temporary deployment, even when the code runs on a laptop.

Origin, host, and HTTPS behavior

The browser or provider sees the public HTTPS origin, while the Localtonet client forwards to a local IP address and port that may use plain HTTP. Applications that generate absolute URLs, enforce allowed hosts, validate callback origins, use secure cookies, or trust forwarded proxy information must be configured for the externally visible origin.

Do not globally disable host validation or TLS-origin checks to make a test pass. Configure the exact test origin using the mechanism supported by the installed framework version. For OAuth, the provider’s registered callback URI must match the public scheme, host, port when present, and callback path expected by the application.

Troubleshooting failed pipeline and tunnel tests

Container binding mistakes

If the application runs inside Docker on the developer machine, a process bound only to the container’s loopback interface may not be reachable from the host. Publish the application port according to the project’s container configuration and verify it from the host before targeting it with Localtonet. Do not guess a container IP that can change between starts.

Failure artifacts that are worth retaining

Capture application startup logs, migration output, sanitized HTTP status and response data, test reports, correlation IDs, provider delivery IDs, and timestamps. Keep artifact retention proportionate to the test and avoid collecting complete webhook bodies when they contain personal or payment-related data. Never upload environment dumps or authorization headers as debugging artifacts.

Complete the test with explicit cleanup

Cleanup is part of the pipeline design, not an optional task after a successful run. The self-contained GitHub Actions environment is discarded after the job, while its explicit if: always() steps preserve diagnostics and stop the application process even when assertions fail.

In the developer-managed architecture, the CI runner does not own the Localtonet tunnel. The device operator must perform cleanup after success, failure, cancellation, or timeout.

Frequently asked questions