Private Databases & Self-Hosted Runners

If your staging or development database is only reachable inside your network (VPN, private VPC, internal subnet), GitHub-hosted runners cannot access it.

This is expected: GitHub-hosted runners run in GitHub’s cloud and only have public internet access.

The correct solution is to run Stoney on a self-hosted GitHub Actions runner inside your private network.

What Is a Runner?

A runner is the machine that executes your GitHub Actions workflow.

Two types:

GitHub-Hosted Runner

• Managed by GitHub
• Ephemeral VM spun up per job
• Public internet access only
• Cannot access private databases or internal services

Self-Hosted Runner

• A machine you control
• Runs inside your infrastructure
• Can access internal databases, APIs, and services
• Registers with GitHub to receive jobs

When using a self-hosted runner, Stoney runs inside your network, so your database never needs to be publicly exposed.

When Do You Need a Self-Hosted Runner?

You need one if:

• Your staging DB is only reachable over VPN
• Your DB lives inside a private VPC
• Your internal APIs are not public
• Security policy forbids exposing infrastructure to the public internet

If your database is publicly reachable and secured properly, a GitHub-hosted runner may work. For most production-grade setups, self-hosted runners are standard.

How It Works (High-Level)

Without a self-hosted runner:

GitHub-hosted runner → ❌ Private DB (blocked)

With a self-hosted runner:

GitHub → Self-hosted runner (inside your network) → ✅ Private DB

GitHub sends the job to your internal machine. That machine executes Stoney and connects to your database locally.

Setting Up a Self-Hosted Runner

1) Provision a machine

Pick a machine that can reach your staging DB:

• VM inside your cloud VPC
• Server on your internal network
• Kubernetes node with access to internal services

It must:

• reach your database host
• have outbound internet access to GitHub

2) Register the runner with GitHub

In your repository:

Settings → Actions → Runners → New self-hosted runner

Follow GitHub’s installation instructions. It typically looks like:

./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN
./run.sh

3) Target the runner in your workflow

Use runner labels:

jobs:
  stoney:
    runs-on: [self-hosted, linux, x64]

Now Stoney runs inside your network boundary.